ovhcloud-docs/docs/en/internal/format-reference.mdx at develop · ovh/ovhcloud-docs

title

Format Reference

description

Internal authoring aid. A single page compiling every supported markdown and MDX format so a single visual pass confirms nothing broke after a theme or build change. Not user-facing.

lastUpdated

2026-10-19

sidebar

false

outline

false

head

Objective

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam vehicula augue sit amet libero fringilla, nec auctor magna pretium. This guide compiles every supported format so that a single visual pass can confirm nothing is broken after a theme or build change.

Requirements

An OVHcloud account with access to the Control Panel
Basic familiarity with Markdown and MDX
A browser to verify that all formats render correctly

Instructions

1 — Plain text and inline formatting

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque habitant morbi tristique senectus. Use inline code to reference technical terms, file paths like /etc/hosts, or commands like sudo systemctl restart nginx.

You can also combine them: bold code or italic code.

Superscript for footnotes¹ and line breaks
between phrases are also supported.

¹ This is a simulated footnote rendered with superscript HTML.

Tooltip example: hover over this word to see the overlay.

Glossary tooltip: the definition below is not written here — it comes from the shared glossary (config/glossary/en.yaml) via .ovhconfig, and is translated per locale. Glossary definitions may link to guides, like snapshot: internal links stay in the same tab and follow the current locale.

2 — Headings

H4 — Fourth-level heading

H5 — Fifth-level heading (use sparingly)

3 — Images

Image from the shared public folder (referenced by absolute path, shared across all locales):

Second image from a different guide folder (still a shared public asset):

4 — Code blocks

Bash:

#!/bin/bash
# Create and mount a logical volume for SAP HANA data
pvcreate /dev/sdb
vgcreate vg_hana /dev/sdb
lvcreate -L 500G -n lv_hanadata vg_hana
mkfs.xfs /dev/vg_hana/lv_hanadata
mount /dev/vg_hana/lv_hanadata /hana/data
echo "Mount successful"

Console (interactive shell output):

$ lsblk
NAME          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
sda             8:0    0 447.1G  0 disk
├─sda1          8:1    0   512M  0 part  /boot/efi
├─sda2          8:2    0     1G  0 part  /boot
└─sda3          8:3    0 445.6G  0 part
  └─md0         9:0    0 445.6G  0 raid1 /
sdb             8:16   0  10.5T  0 disk

$ df -h /hana/data
Filesystem                       Size  Used Avail Use% Mounted on
/dev/mapper/vg_hana-lv_hanadata  500G  1.2G  499G   1% /hana/data

JSON:

{
  "serviceName": "pcc-1-2-3-4",
  "ram": 512,
  "storage": {
    "type": "NVMe",
    "sizeGb": 10240
  },
  "tags": ["production", "sap-hana"]
}

YAML:

version: "3.8"
services:
  app:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro

5 — Callouts

:::info Info callout — Lorem ipsum dolor sit amet, consectetur adipiscing elit. Use this for neutral supplementary information that helps the reader but is not critical. :::

:::tip Tip callout — Pellentesque habitant morbi tristique senectus et netus. Use tips to share best practices or shortcuts. :::

:::warning Warning callout — Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Use warnings when the user must pay attention to avoid data loss or service disruption.

This warning has a list item
And another one

:::

:::danger Danger callout — Ut enim ad minim veniam, quis nostrud exercitation. Use danger for irreversible or destructive actions. :::

Empty blockquote (plain > syntax, no type annotation):

Lorem ipsum dolor sit amet, consectetur adipiscing elit. This is an unstyled blockquote, also known as an "empty" callout.

6 — Details (collapsible sections)

:::details Click to expand — Basic collapsible

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.

Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit.

:::

Click to expand — Collapsible with rich content

This collapsible contains multiple content types:

A code block:

echo "Hello from inside a collapsible"

A table:

Parameter	Type	Description
`host`	string	The target hostname or IP
`port`	number	The port to connect to
`timeout`	number	Connection timeout in ms

An info callout:

:::info You can nest callouts inside collapsibles. :::

6b — Reusable text fragments

Standard blocks that must read identically on every page (support scope, recurring boilerplate) are maintained centrally in config/fragments/<key>/<locale>.md — one markdown body per locale — and inserted with a token on its own line, surrounded by blank lines:

[[fragment:<key>]]

Available keys: support-scope — the support-scope disclaimer; professional-services — the Professional Services sentence of the Go further section.

Never paraphrase or paste the text into a guide. Insert the token — [[fragment:<key>]] — so all pages stay in sync; the wording is edited once, centrally.
Tokens resolve per locale at build time, before compilation, so a fragment may itself contain /links/ targets.
A key whose body carries a numbered note (<sup>1</sup>) also accepts [[fragment:<key>|n=3]], which renders the same body with the note numbered 3 — for a guide whose other footnotes push the note down the sequence. Combine with the pin as [[fragment:<key>|n=3|en]] (|en|n=3 renders the same).
An unknown or misspelled key fails the build (remarkNoUnresolvedFragments).
On a page whose prose is untranslated English — typically an EN guide that other locales reach through a symlink — pin the token to English with [[fragment:<key>|en]], so the reader does not get a localised block sitting under English prose. pnpm fragment:validate enforces this on every symlinked guide, and requires all tokens on a page to agree (either every one carries |en or none does). The same modifier exists for CP-NAV tokens: [[cpnav:<key>|en]].

6c — Control Panel navigation blocks

A guide whose instructions begin in the OVHcloud Control Panel opens with a navigation block: a heading, a direct link to the destination, and the path through the Manager's sidebar. Blocks are generated from config/cpnav/keys/<key>.ts — one file per key, registered in config/cpnav/index.ts — and inserted with a token on its own line, surrounded by blank lines:

[[cpnav:<key>]]

pnpm cpnav:validate lists the keys, the combinations in use and where each is used.

Never write the block by hand. Insert the token, so a Manager rename is corrected once in the key instead of in every guide that names it.
Labels are Manager-authoritative. They must match what the reader sees in their own sidebar, including the Manager's own inconsistencies — a better translation than the Manager's is a worse label, because the reader cannot find it. Read them from the nav tree; never invent them. pnpm cpnav:new <key> --universe=<universe> scaffolds a key and points at the lookup.
A guide that reaches two destinations in parallel — the reader uses one or the other — names both in one token: [[cpnav:<key>+<key>]]. A guide with one primary task and supporting visits keeps the single key of its main screen.
Key order inside a multi-key token is fixed by the registry's declaration order, and any other spelling fails the build. pnpm cpnav:token <key> <key> prints the canonical form. Combinations are discovered from the guides, so none has to be declared before it is used.
An unknown key, an unknown modifier or a non-canonical key order fails the build (remarkNoUnresolvedCpnav).
On a page whose prose is untranslated English, pin the block with [[cpnav:<key>|en]], exactly as for fragments above. pnpm cpnav:validate enforces this.

7 — Tables

Simple table:

Logical volume	Recommended size
`/usr/sap`	MIN(32 GB)
`/hana/data`	1 × RAM
`/hana/log`	½ × RAM (max 512 GB)
`/hana/shared`	MIN(1 × RAM, 1 TB)
`/hana/backup`	`/hana/data` + `/hana/log`

Table with HTML line breaks in cells:

Condition	Formula
RAM ≤ 512 GB	`/hana/log` = ½ × RAM Example: 256 GB RAM → 128 GB log
RAM > 512 GB	`/hana/log` = 512 GB (fixed cap) Example: 1 TB RAM → 512 GB log

8 — Lists

Unordered list:

Lorem ipsum dolor sit amet
Consectetur adipiscing elit
Sed do eiusmod tempor incididunt

Nested unordered list:

Universe level
- Product level
  - Section level
    - Guide level (deepest nesting)
- Another product
  - Its section

Numbered list:

Connect to the OVHcloud Control Panel.
Navigate to Bare Metal Cloud > Dedicated Servers.
Select your server from the list.
Click the Install button to launch the reinstallation wizard.
Confirm your choice in the modal dialog.

Numbered list with a custom start value:

Review the partition layout proposed by the wizard.
Click Confirm to finalize the installation.

9 — Links

Internal link (guide path): All about your OVHcloud username

Internal link (shortcut alias): OVHcloud Control Panel

External link: OVHcloud community forum

Link inside a sentence: To manage your SSH keys, log in to the OVHcloud Control Panel and navigate to My account > SSH keys.

<ManagerLink> also takes a brands prop: a list of brands, same shape as regions, defaulting to ['ovh']. It has the same meaning on <Api> and <ApiLink> below, and this note is the canonical description of it.

Whenever brands includes 'ks'/'sys', to/authFlow (and urls/regionMeta) have no effect: the Kimsufi/So you Start manager login URLs are built in-component, on a different domain and scheme than OVHcloud's manager.

A Kimsufi / So you Start manager link — no to needed, the picker offers all 4 endpoints in brands order, so here So you Start EU/CA, then Kimsufi EU/CA:

<ManagerLink brands={['sys', 'ks']}>the Kimsufi/So you Start manager

Every OVHcloud region and every Kimsufi/So you Start endpoint in one picker:

<ManagerLink brands={['ovh', 'sys', 'ks']}>every Control Panel

Inline code outside a link: Use the --force flag only when you are certain the operation is safe.

Inline code inside a link: See the /me/api/credential endpoint reference for authentication details.

Sentence mixing both: the GET /me call returns your account details, whereas plain text links like the Control Panel do not use code formatting.

10 — API calls

Single GET call:

POST call with a path parameter:

PUT call limited to EU and CA regions:

DELETE call:

GET call on a Kimsufi / So you Start route — brands, and no version, since these brands have no versioned API like OVHcloud's; passing a version other than 'v1' with them logs a development-only console warning. The default offers all 4 endpoints in brands order, so here So you Start EU/CA, then Kimsufi EU/CA:

Same route, restricted to So you Start via brands and to EU via regions:

'ovh', 'ks' and 'sys' are independently selectable: mixing all 3 shows every OVHcloud region and every Kimsufi/So you Start endpoint in one picker. One regions value is applied to both families, which holds only while the OVHcloud and Kimsufi/So you Start region sets coincide on EU/CA — the code keeps them as two separate sets, not one shared list. version defaults to 'v1' for the 'ovh' brand if omitted:

10b — Zone-aware API links

Generic links to the OVHcloud API follow the reader's commercial zone (EU / CA), like Control Panel links do. Both components are globally registered — no import needed. Do not use /links/api, /links/console or hardcoded https://api.eu.ovhcloud.com/… URLs.

A generic reference to the API or the API console (targets the zone's gateway page):

You can also do this with the OVHcloud API.

A section deep link — opens the console with the section selected (zone-aware, unlike a hardcoded ?section= URL):

All API routes used in this guide are available under the /dedicated/nasha section of the API console.

An operation deep link — same target as an <Api> pill, but rendered as a normal inline link with custom text (for tables and prose where a pill doesn't fit):

Data	Access
API call logs	<ApiLink section="/me" method="GET" route={"/me/api/logs/self"} regions={["eu"]}>List of API calls done with your account
Audit logs	<ApiLink section="/me" method="GET" route={"/me/logs/audit"}>Get your audit logs

The first row's operation exists only in the EU API (the EU and CA schemas differ per route) — regions={["eu"]} restricts it, which renders a plain direct link to the EU console for every reader. The second row exists in both schemas, so it stays zone-aware. When migrating hardcoded links, verify each route against both region schemas and restrict regions where they differ.

An EU-only product — offered zones derived from the route (SMS is EU-only):

Check your jobs with <ApiLink section="/sms" method="GET" route={"/sms/{serviceName}/jobs"}>this API call.

A Kimsufi / So you Start operation deep link — same brands/regions props as <Api>. For these brands, route + method alone reaches the operation and section alone lands on the section. The 'ovh' brand differs: section is what builds its deep link, and without it its entries fall back to the API gateway home page:

Consult your server's details in <ApiLink brands={['sys', 'ks']} method="GET" route={"/dedicated/server/{serviceName}"}>the Kimsufi/So you Start console.

Restricted to So you Start EU only, same as the <Api> example above:

See <ApiLink brands={['sys']} regions={["eu"]} method="GET" route={"/dedicated/server/{serviceName}"}>this endpoint.

Every OVHcloud region and every Kimsufi/So you Start endpoint in one picker — brands takes the same values on all three components, as described in the <ManagerLink> note above. section is what gives the eu/ca entries their deep link; without it they would fall back to the API gateway home page, while the Kimsufi/So you Start entries would still reach the operation:

See <ApiLink brands={['ovh', 'sys', 'ks']} section="/dedicated/server" method="GET" route={"/dedicated/server/{serviceName}"}>this endpoint on any dedicated server brand.

A token-creation link with pre-filled rights:

Generate OVHcloud API tokens

An EU-only product — the offered zones are derived from the product paths in rights:

Create your SMS API credentials

11 — Tabs

Basic tabs:

ssh ubuntu@192.0.2.1 -i ~/.ssh/my_key

ssh ubuntu@192.0.2.1 -i C:\Users\user\.ssh\my_key

Open PuTTY and enter 192.0.2.1 in the Host Name field. Under Connection > SSH > Auth, browse to your private key file (.ppk format).

Tab sync & the noSync opt-out: tab blocks that share the same labels stay in sync and remember the choice across pages — this is automatic, no groupId needed. Numbered "Step" sets (e.g. Step 1 / Step 2 / Step 3 - IMAP) are detected and kept independent so they never sync. To stop a non-sequential block from syncing, add noSync:

This block keeps purely local state — it will not sync with other Plan A / Plan B blocks, nor persist the selection across navigation.

Independent local state only.

12 — Embedded video

12b — Guided-tour iframe

12c — Mermaid diagrams

Write a fenced mermaid block; the site renders it (components/MermaidDiagram, settings in config/mermaid.ts):

The whole diagram is always visible. A diagram wider than the text column is scaled down to fit it; a click enlarges it to the screen, like an image (a click anywhere or Esc closes it).
When an arrow crosses a frame title, a gap opens between two words under the arrow, so the arrow and its head stay visible and no word is hidden. The content of a frame is centred in it. Both are done at render time: the source is never changed.
An invalid diagram shows an error message with its source instead of a blank.

Rules for authors:

Do not change the orientation of a diagram (flowchart LR, TB, a subgraph direction) just to make it fit: readers zoom. Re-orienting it because the diagram reads better that way is your call.
Keep labels short. A very wide diagram (many blocks side by side) becomes small on a laptop screen.
When you colour a block (style X fill:…), also set a text colour that contrasts with it (color:#…): dark text on a light fill, white text on a dark fill only.
Do not add layout aids by hand (#nbsp; padding, invisible blocks, ~~~ links): the renderer centres frames and clears titles itself.

At commit time, pnpm mermaid:lint checks the staged diagrams: an invalid diagram blocks the commit; a changed orientation (to confirm it is intended), a text colour that does not contrast with its fill, or a hand-made layout aid is reported as a warning.

The diagram below has a frame title crossed by an arrow and a block that Mermaid places off-centre in its frame — check the gap under the arrow, the centred block, and the zoom:

flowchart TB
    U[Users and administrators]
    subgraph OVH["Operated by OVHcloud"]
        CP["Kubernetes control plane<br/>API server, etcd, controllers, scheduler"]
    end
    subgraph PN["Private network (Public Cloud or vRack)"]
        N["Worker nodes and pods<br/>CNI: Canal (Free) or Cilium (Standard)"]
    end
    GW["Gateway (OpenStack router)<br/>SNAT, outbound only"]
    LB["Load Balancer (Octavia)<br/>with a Floating IP, inbound"]
    I((Internet))
    U -- "kubectl, public API server endpoint" --> CP
    CP <-.->|"Konnectivity"| N
    N --> GW --> I --> LB --> N

13 — Russian-doll (nested formats)

The following tabs each contain multiple nested format types.

Use the following API call to retrieve your service information:

:::info This endpoint returns a paginated list. Use the offset and limit query parameters to navigate through results. The maximum page size is 100. :::

:::warning Logs are retained for 90 days only. Archive them regularly if you need a longer audit trail. :::

The Control Panel dashboard displays your active services:

:::tip Click the shortcut icons at the top of the dashboard to jump directly to the most-used sections of your account. :::

:::details Expand to see the full configuration file

# /etc/hana/global.ini
[persistence]
basepath_datavolumes = /hana/data/SID
basepath_logvolumes  = /hana/log/SID

[communication]
listeninterface = .global

Recommended disk layout for this configuration:

Mount point	File system	Mount options
`/hana/data`	XFS	`noatime,nodiratime,logbsize=256k`
`/hana/log`	XFS	`noatime,nodiratime,logbsize=256k`
`/hana/shared`	NFS or XFS	`rw,bg,hard,timeo=600,rsize=1048576`

:::

Troubleshooting — mount errors at boot

If /hana/data fails to mount on boot, check that the UUID in /etc/fstab matches the actual device:

$ blkid /dev/vg_hana/lv_hanadata
/dev/vg_hana/lv_hanadata: UUID="a1b2c3d4-e5f6-7890-abcd-ef1234567890" TYPE="xfs"

$ grep hana /etc/fstab
UUID=a1b2c3d4-e5f6-7890-abcd-ef1234567890  /hana/data  xfs  noatime,nodiratime,logbsize=256k  0 0

:::danger Do not use /dev/sdX paths in /etc/fstab. Device names are not stable across reboots. Always use UUIDs or LVM paths. :::

Steps to authorize an API token:

Retrieve your current NIC handle:

Grant the token the required scope via the Control Panel:

Verify the token is active:

Go to Account > API > Active tokens
Check the expiry date column
Revoke any tokens that are no longer needed:
- Click the ... menu
- Select Revoke
- Confirm the action

:::warning Tokens with the full-access scope should be rotated every 90 days as a security best practice. :::

14 — Russian-doll: formats inside a Details

Expand — API call, image, callout, code block, table and nested list inside a collapsible

Use this API call to list your active credentials:

The Control Panel shows the same data under Account > API > My credentials:

:::info Credentials created via the API and credentials created via the Control Panel are interchangeable — they share the same underlying token store. :::

:::warning If you rotate a credential that is embedded in an automation script, update the script before revoking the old credential, or your automation will fail. :::

Revoke a credential by its ID with:

# Replace <credentialId> with the numeric ID returned by the GET call above
curl -X DELETE "https://api.eu.ovhcloud.com/v1/me/api/credential/<credentialId>" \
  -H "X-Ovh-Application: <appKey>" \
  -H "X-Ovh-Consumer: <consumerKey>" \
  -H "X-Ovh-Timestamp: $(date +%s)" \
  -H "X-Ovh-Signature: <signature>"

Recommended rotation schedule by credential scope:

Scope	Rotation interval	Automation-safe?
`full-access`	30 days	No — manual only
`read-only`	90 days	Yes
`scoped`	60 days	Yes

Steps to rotate safely:

Create the new credential via the API or Control Panel.
Update all scripts and CI/CD pipelines that use the old credential:
- Check your .env files and secret stores
- Check scheduled jobs and cron tasks
  - Look for hardcoded tokens in shell scripts
  - Look for tokens injected as environment variables
Validate that the new credential works end-to-end.
Revoke the old credential.

15 — Nested Details (russian-doll collapsibles)

Two depth levels of collapsibles using raw HTML <details>. The Rspress container syntax (:::details) does not support nesting — use HTML for any nested case.

Outer collapsible — click to expand

The outer block can contain any MDX content.

Inner collapsible — click to expand

The inner block is fully nested.

A list item
Another list item

echo "Inner code block"

:::info Callouts also render inside nested collapsibles. :::

Back at the outer level after the inner closes.

Go further

Join our community of users.

Navigation Menu

Repository navigation

format-reference.mdx

format-reference.mdx

Objective

Requirements

Instructions

1 — Plain text and inline formatting

2 — Headings

H4 — Fourth-level heading

H5 — Fifth-level heading (use sparingly)

3 — Images

4 — Code blocks

5 — Callouts

6 — Details (collapsible sections)

6b — Reusable text fragments

6c — Control Panel navigation blocks

7 — Tables

8 — Lists

9 — Links

10 — API calls

10b — Zone-aware API links

11 — Tabs

12 — Embedded video

12b — Guided-tour iframe

12c — Mermaid diagrams

13 — Russian-doll (nested formats)

14 — Russian-doll: formats inside a Details

15 — Nested Details (russian-doll collapsibles)

Go further

FilesExpand file tree

format-reference.mdx

Latest commit

History

format-reference.mdx

File metadata and controls

Objective

Requirements

Instructions

1 — Plain text and inline formatting

2 — Headings

H4 — Fourth-level heading

H5 — Fifth-level heading (use sparingly)

3 — Images

4 — Code blocks

5 — Callouts

6 — Details (collapsible sections)

6b — Reusable text fragments

6c — Control Panel navigation blocks

7 — Tables

8 — Lists

9 — Links

10 — API calls

10b — Zone-aware API links

11 — Tabs

12 — Embedded video

12b — Guided-tour iframe

12c — Mermaid diagrams

13 — Russian-doll (nested formats)

14 — Russian-doll: formats inside a Details

15 — Nested Details (russian-doll collapsibles)

Go further