> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ovh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```bash Repository structure theme={null}
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
```
```bash Guide with images theme={null}
pages/
└── my-super-guide/
├── images/
│ ├── 01.png
│ └── 02.png
├── guide.en-gb.md
└── meta.yaml
```
Each guide must be placed in a folder with a representative name.
## File naming convention
Every file must follow this naming pattern:
```
.-.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`
| Code | Language |
| ---- | ---------- |
| `de` | German |
| `en` | English |
| `es` | Spanish |
| `fr` | French |
| `it` | Italian |
| `pl` | Polish |
| `pt` | Portuguese |
| 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 |
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:
```yaml theme={null}
---
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:
```yaml theme={null}
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](https://www.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.
```markdown theme={null}
```
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.
```markdown theme={null}
## 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..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..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:
```markdown Alert theme={null}
> [!alert]
>
> This is an alert!
>
```
```markdown Primary notice theme={null}
> [!primary]
>
> This is a primary notice!
>
```
```markdown Warning theme={null}
> [!warning]
>
> This is a warning!
>
```
```markdown Info theme={null}
> [!info]
>
> This is a simple notice!
>
```
### Tabs
Use tabs to present alternative instructions (for example, different operating systems or methods):
````markdown theme={null}
> [!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:
```markdown theme={null}
> [!faq]
>
> Question 1
>> Response 1
> Question 2
>> - item 1
>> - item 2
```
### Carousel
Use the carousel block to display multiple images with captions:
```markdown theme={null}
> [!carousel]
>
> - 
> - 
> - 
>
```
### API block
Use the API block to reference an OVHcloud API endpoint:
```markdown theme={null}
> [!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