Aller au contenu principal

Guide de style du contenu

Tous les niveaux

C'est la cohérence qui rend une référence digne de confiance. Suivez ces règles et votre PR passera la relecture sans encombre.

La voix​

  • Claire et directe. Des phrases courtes. Commencez par l'essentiel.
  • Amicale, jamais ampoulée. Supprimez « dans le monde trépidant d'aujourd'hui ». Respectez le temps du lecteur.
  • Tranchée, puis honnête. Donnez d'abord la seule manière recommandée, puis mentionnez les alternatives et les compromis.
  • Des exemples plutôt que de la théorie. Montrez un extrait ou un cas concret ; ne vous contentez pas de décrire.
  • Anglais américain.

Structure d'une page​

---
sidebar_position: 2
title: "Your Page Title"
description: "One sentence for search and previews."
---

<LevelBadge level="beginner" />

A one or two sentence intro that states what the reader will get.

## Sections with ## headings
...

## Next
- 2–4 links to related pages
  • Commencez par le badge de niveau (beginner | intermediate | advanced | all). Les composants sont globaux — ne les importez pas.
  • Terminez par une liste « Suite » / « Voir aussi » de 2 à 4 liens internes.
  • Utilisez les admonitions (:::tip, :::warning, :::note, :::info) pour mettre en valeur, avec parcimonie.

Les deux règles strictes​

:::warning Non négociable

  1. Citez vos sources pour les faits volatils. Noms de modèles, prix, limites, drapeaux exacts, fonctionnalités en bêta → liez la source officielle et ajoutez <VerifyNote lastVerified="YYYY-MM-DD" source="…">. Ne codez jamais en dur les faits relatifs aux modèles — renvoyez vers le tableau des modèles. Détails : Vérification des faits.
  2. N'inventez rien. Pas de statistiques, de citations, d'API ou de fonctionnalités inventées. En cas de doute, dites-le ou indiquez [verify]. :::

Opinion vs officiel​

  • Nous sommes tranchés — c'est là tout l'intérêt. Recommandez, ne vous contentez pas d'énumérer.
  • Mais la documentation officielle fait foi. Déférez-y, liez-la, et ne la contredisez jamais en silence.

Pièges du MDX​

  • Les accolades {comme ceci} dans la prose sont interprétées comme du code par MDX — mettez-les entre backticks ou dans des blocs de code, ou utilisez [des crochets] dans les exemples.
  • Testez en local : npm run build doit réussir (il échoue sur les liens cassés).

Suite​