Documentation style guide

Writing standards, file structure, naming conventions, and Markdown formatting for OVHcloud guides.

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.

Repository structure

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

Component	Description
content-type	One of: home, universe, product, guide
language	ISO 639-1 language code (see list below)
zone	ISO 3166-1 country/region code (see list below)

Examples: guide.en-gb.md, universe.fr-fr.md, product.de-de.md

Supported languages

Code	Language
de	German
en	English
es	Spanish
fr	French
it	Italian
pl	Polish
pt	Portuguese

Supported zones

Code	Region
asia	Asia
au	Australia
ca	Canada
de	Germany
es	Spain
fr	France
ie	Ireland
it	Italy
gb	United Kingdom
pl	Poland
pt	Portugal
sg	Singapore
us	World English / World Spanish

Authorized language-zone combinations

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
---

Field	Description	Required
title	Title of the guide	Yes
excerpt	Short description of the guide	Yes
hidden	Set 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

Field	Description	Required
id	UUID4 unique identifier for the guide	Yes
full_slug	The slug component of the guide’s URL	Yes

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

> [!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

Carousel

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