# Écrire une page

Le résultat : une page MDX publiée à une adresse qui suit son chemin dans le dossier.

**Avant de commencer** : un dossier de doc qui se construit ([Ta première doc en local](/docs/demarrer/premiere-doc/)).

## Le fichier et son adresse

Chaque page est un fichier `.mdx` ou `.md`. Le chemin donne l’adresse : `guides/publier.mdx` devient `/guides/publier/`, et `index.mdx` à la racine devient l’accueil.

Pour qu’une page apparaisse dans le menu, ajoute son chemin, sans extension, dans [`navigation`](/docs/guides/navigation/).

## Métadonnées

Le haut de la page, entre deux lignes `---`, décrit la page :

```mdx
---
title: Publier avec Host
sidebarTitle: Publier
description: Mettre la doc en ligne et brancher l'assistant.
---
```

| Champ          | Rôle                                                                                  |
| -------------- | ------------------------------------------------------------------------------------- |
| `title`        | Titre de la page. Il sert aussi de titre de l’onglet du navigateur.                   |
| `sidebarTitle` | Libellé plus court dans la barre latérale.                                            |
| `description`  | Une phrase. Elle est reprise par les moteurs de recherche, `llms.txt` et l’assistant. |

## Titres et sections

Commence les sections par `##`. Chaque titre reçoit une ancre : `## Relier la console` donne `#relier-la-console`. L’assistant cite ces ancres dans ses sources. Un titre court et précis donne donc une source claire.

> **Astuce**
>
> Une section par question que l’on te pose. Une section courte, au titre simple, est retrouvée plus souvent.

## Liens

Écris les liens depuis la racine de ta doc, avec le chemin de la page :

```mdx
[Publier avec Host](/guides/publier/)
[Le domaine](/guides/publier/#ton-domaine)
[La référence](/reference/docs-json/)
```

Pour un lien vers un autre produit, donne son adresse complète. Quand la doc est servie sous un sous-chemin (`base`), Docs ajoute ce sous-chemin au build : ne l’écris pas toi-même.

## Images

Range les images dans un dossier d’images (`images/`, `img/`, `logo/`, `assets/` ou `static/`), ou dans `public/` pour les fichiers servis à la racine. Cite-les avec un chemin qui commence par `/` :

```mdx
![Le tableau de bord](/images/tableau-de-bord.png)
```

Pour une légende, entoure l’image d’un cadre :

```mdx
<Frame caption="Le tableau de bord après la première publication">
  ![Le tableau de bord](/images/tableau-de-bord.png)
</Frame>
```

Donne toujours un texte alternatif : il sert aux lecteurs d’écran et aux agents.

## Code

Indique le langage après les trois accents graves. Le bloc est coloré et reçoit un bouton **Copier** :

````mdx
```bash
npm run build
```
````

## Ce qui n’est pas publié

- Les fichiers dont le nom commence par `_`.
- Les dossiers cachés (dont le nom commence par `.`), `node_modules` et `dist`.
- Les médias rangés hors d’un dossier d’images ou de `public/`. Le logo et le favicon déclarés dans `docs.json` sont publiés dans tous les cas.

## Si ça ne marche pas

- **Une page apparaît dans `docs.json` sans fichier** : le build s’arrête avec la liste des fichiers manquants. Vérifie le chemin, en minuscules, sans extension.
- **Une image ne s’affiche pas** : elle n’est pas dans un dossier d’images ni dans `public/`, ou son chemin ne commence pas par `/`.
- **Un composant s’affiche comme du texte brut** : son nom ne figure pas dans la [référence des composants](/docs/reference/composants/). Vérifie l’orthographe, majuscules comprises.