Les composants Docsy s’écrivent directement en Markdown. Les réglages restent dans YAML ; le contenu reste lisible dans votre dépôt et dans les exports pour les agents. Aucun service de rédaction ni police distante n’est nécessaire.

Encadrés

Chaque type possède une icône et un accent discret. Le titre explique la situation ; le corps indique quoi faire. La distinction ne repose pas uniquement sur la couleur.

Code example
:::warning[Gardez vos secrets hors du dépôt]
Lisez les identifiants privés depuis l’environnement du serveur.
:::

Étapes numérotées

  1. Générez un projet. Partez de l’interface modifiable de Docsy.

  2. Configurez les sources. Déclarez les articles, la spécification API et les métadonnées SDK dans YAML.

  3. Validez et publiez. Vérifiez le résultat avant de le déployer.

Placez une liste Markdown ordonnée entre :::steps et :::. Les paragraphes et les blocs de code peuvent faire partie d’une étape.

Onglets synchronisés

Les groupes utilisant la même clé sync mémorisent le même libellé dans le stockage local du navigateur.

npm

Code example
npm run validate
npm run build

pnpm

Code example
pnpm validate
pnpm build

Utilisez quatre deux-points pour le groupe tabs et trois pour chaque enfant tab. Le clavier permet de naviguer avec les flèches, Début et Fin. Sans JavaScript, tous les panneaux restent visibles.

Groupes de code

Entourez les blocs de code avec :::code-group. Le texte placé après la langue du bloc devient le libellé de l’onglet.

JavaScript

JavaScript
console.log('Une documentation qui vous appartient.');

Python

Python
print('Une documentation qui vous appartient.')

Explications repliables

Que se passe-t-il sans JavaScript ?

Les onglets restent lisibles et les sections repliables utilisent l’élément natif details du navigateur. La recherche indexe tous les panneaux, pas uniquement celui qui est sélectionné.

Extraits réutilisables

Déclarez les fichiers Markdown dans YAML :

Code example
content:
  snippets:
    publicationFr: content/snippets/publishing-checklist.fr.md

Insérez ensuite ::include{src="publicationFr"} sur sa propre ligne :

  • Validez les sources configurées, les liens internes et les ancres.
  • Construisez les versions et les langues que vous souhaitez publier.
  • Vérifiez les exemples et les permissions avant le déploiement.

Les extraits sont développés dans les articles, la recherche, les exports Markdown et les documents JSON. Les noms inconnus, les cycles, les chemins hors du projet et plus de dix inclusions imbriquées font échouer la validation.

Choisir les composants autorisés

Code example
content:
  components: [note, tip, warning, danger, steps, tabs, accordion, code-group, include]

Un composant inconnu, désactivé ou mal structuré empêche la publication. Le composant tab doit toujours être un enfant de tabs.