Skip to main content
All OVHcloud guides are written in Markdown with custom extensions. This page covers how the repository is structured, how files must be named, what metadata is required, and how to use the extended Markdown syntax.

​
Repository structure

Guides are organized in a three-level hierarchy: universe → product → guide. All content lives under the pages/ folder. 
pages/
├── web/                          # universe
│   ├── universe.en-gb.md
│   ├── universe.fr-fr.md
│   ├── domains/                  # product
│   │   ├── product.en-gb.md
│   │   ├── product.fr-fr.md
│   │   └── glue-registry/        # guide
│   │       ├── guide.en-gb.md
│   │       └── guide.fr-fr.md
├── home.en-gb.md
└── home.fr-fr.md
Each guide must be placed in a folder with a representative name.

​
File naming convention

Every file must follow this naming pattern: 
<content-type>.<language>-<zone>.md
ComponentDescription
content-typeOne of: home, universe, product, guide
languageISO 639-1 language code (see list below)
zoneISO 3166-1 country/region code (see list below)
Examples: guide.en-gb.md, universe.fr-fr.md, product.de-de.md
CodeLanguage
deGerman
enEnglish
esSpanish
frFrench
itItalian
plPolish
ptPortuguese
CodeRegion
asiaAsia
auAustralia
caCanada
deGermany
esSpain
frFrance
ieIreland
itItaly
gbUnited Kingdom
plPoland
ptPortugal
sgSingapore
usWorld English / World Spanish
The exhaustive list of authorized language suffixes is:de-de, en-asia, en-au, en-ca, en-ie, en-gb, en-us, es-es, es-us, fr-ca, fr-fr, it-it, pl-pl, pt-pt

​
Guide metadata (YAML frontmatter)

Each guide file opens with a YAML frontmatter block: 
---
title: Title of the guide
excerpt: Short description of the guide
hidden: false
---
FieldDescriptionRequired
titleTitle of the guideYes
excerptShort description of the guideYes
hiddenSet to true to hide from navigation (default: false)No
The slug, section, and order fields are deprecated. Do not use them in new guides.

​
meta.yaml file

Every guide folder must contain a meta.yaml file with the following fields: 
id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
full_slug: product-category-guide-name
FieldDescriptionRequired
idUUID4 unique identifier for the guideYes
full_slugThe slug component of the guide’s URLYes
Generate a UUID4 at uuidgenerator.net/version4 or with uuidgen in a terminal. Base the full_slug on related existing guides, include only important keywords, and keep it short.

​
Images

Store images in an images/ subfolder inside the guide’s folder. Reference them with a relative path from the guide file. 
![Alt text describing the image](images/01.png)
Image requirements:
  • Format: .png only
  • Width: Resize images that exceed 1400px wide
  • Language: Use the English UI when taking screenshots
  • Highlights: Use OrangeSunrise (#ff9803 — RGBA: 255, 152, 3, 1) for highlighting
  • Privacy: Blur or remove IPs, user IDs, private URLs, and any other sensitive information

​
Index structure

The pages/index.md file is the single source of truth for how guides are organized on the public documentation website. The index supports up to three category levels below the Knowledge Base root. Use four-space increments for indentation. 
## Contents
+ Knowledge base
    + [L1 category](full-slug)
        + [L2 category](full-slug)
            + [English title of the guide](repository-guide-path)
Category labels and titles are all in English. Translations for L1 and L2 categories are maintained in the index-translations.<language>.yaml files. When you add a new guide, update the index to list it in the correct category. If the category does not exist yet, you can create it — but you must also add its translations to all seven index-translations.<language>.yaml files.

​
Custom Markdown extensions

OVHcloud guides extend standard Markdown with several custom block types using the > [!type] blockquote syntax.

​
Notice blocks

Use notice blocks to call out important information: 
> [!alert]
>
> This is an alert!
>

​
Tabs

Use tabs to present alternative instructions (for example, different operating systems or methods): 
> [!tabs]
> Tab title 1
>> Some *content*
> Tab title 2
>> Some *content*
> Tab title 3
>> ```
>> Some content
>> ```

​
FAQ

Use the FAQ block for structured question-and-answer content: 
> [!faq]
>
> Question 1
>> Response 1
> Question 2
>> - item 1
>> - item 2
Use the carousel block to display multiple images with captions: 
> [!carousel]
>
> - ![Caption of image 1](images/01.png)
> - ![Caption of image 2](images/02.png)
> - ![Caption of image 3](images/03.png)
>

​
API block

Use the API block to reference an OVHcloud API endpoint: 
> [!api]
>
> @api {v1} /ipLoadbalancing POST /ipLoadbalancing/{serviceName}/tcp/route
>

​
Writing standards

Follow these standards across all guides:
  • Write in second person (“you”) and active voice
  • Verify and test every action you describe — do not write about anything you cannot test yourself
  • Use the same layout and structure as existing guides; treat them as templates
  • Use English UI screenshots wherever possible
  • Keep guides focused on a single task or concept
  • Use descriptive commit messages

Build docs developers (and LLMs) love

Get started for freeTalk to us