Compétence Markdown pour mdsvr
Générer un ensemble complet, valide et multi-fichiers de documentation Markdown destiné à mdsvr — prend en charge à la fois le mode serveur et l'export statique.
Lorsque cette compétence est déclenchée, produisez plusieurs fichiers .md formant un site
de documentation cohérent, en suivant rigoureusement toutes les conventions de mdsvr.
Étape 1 — Comprendre la demande
Avant de générer les fichiers, extrayez de la demande de l'utilisateur :
- Sujet / nom du produit — qu'est-ce qui est documenté ?
- Public cible — développeurs, utilisateurs finaux, équipes ops, etc.
- Portée — combien de pages / sections sont nécessaires ?
- Langue — français, anglais, ou bilingue ?
- Diagrammes nécessaires ? — si oui, lisez
references/rules/mermaid.mdpour les règles de syntaxe.
Si l'un de ces points n'est pas clair, posez UNE question ciblée avant de continuer.
Étape 2 — Planifier la structure des fichiers
Concevez une hiérarchie logique avant d'écrire le contenu. Un site de documentation mdsvr typique :
docs/
├── README.md ← Page d'accueil (obligatoire)
├── 01-prise-en-main/
│ ├── README.md ← Index de section
│ ├── 01-installation.md
│ ├── 02-demarrage-rapide.md
│ └── 03-configuration.md
├── 02-guides/
│ ├── README.md
│ ├── 01-utilisation-base.md
│ └── 02-avance.md
├── 03-reference-api/
│ ├── README.md
│ └── 01-endpoints.md
└── 04-depannage.md
Adaptez la structure au sujet de l'utilisateur. Augmentez ou réduisez l'échelle selon les besoins.
Étape 3 — Appliquer les règles de fichiers et de liens de mdsvr (OBLIGATOIRE)
3.1 Règles de nommage des fichiers
| Règle | ❌ Incorrect | ✅ Correct |
|---|---|---|
| Pas de points au milieu du nom | 0.1.demarrage-rapide.md | 01-demarrage-rapide.md |
| Pas de points au milieu du nom | config.v2.md | config-v2.md |
| Utiliser le kebab-case | DemarrageRapide.md | demarrage-rapide.md |
| Utiliser un préfixe numérique pour l'ordre | guide.md (dans la barre latérale) | 01-guide.md |
| Noms descriptifs | page1.md | installation.md |
| L'index du dossier doit être | index.md | README.md |
3.2 Règles de structure des liens
| Règle | ❌ Incorrect | ✅ Correct |
|---|---|---|
| Utiliser uniquement des chemins relatifs | [Guide](/docs/guide) | [Guide](./guide) |
Pas d'extension .md dans les liens | [Installation](./installation.md) | [Installation](./installation) |
| Lien vers le dossier, pas vers README | [Début](./01-prise-en-main/README) | [Début](./01-prise-en-main) |
| Les liens d'ancrage doivent correspondre aux titres | [Voir](#etapes-install) (si le titre n'existe pas) | Correspondre exactement |
3.3 Règles de structure des titres
| Règle | ❌ Incorrect | ✅ Correct |
|---|---|---|
| Chaque page a besoin d'un H1 | (la page commence par H2) | # Titre de la page comme premier titre |
| Ne pas sauter de niveaux de titres | H1 → H3 | H1 → H2 → H3 |
| Les titres doivent être descriptifs | ## Section 1 | ## Configuration requise |
Étape 4 — Appliquer le frontmatter à chaque fichier
Chaque fichier .md doit inclure un frontmatter YAML pour le référencement et les métadonnées mdsvr :
---
title: "Titre de la page"
description: "Description en une phrase du contenu de cette page."
---
Étape 5 — Directives de contenu
README.md (Page d'accueil) — Obligatoire
- Doit exister à la racine du dossier docs.
- Inclure : aperçu du projet, liens de navigation rapide vers toutes les sections.
- Utiliser un encart de bienvenue si approprié.
README.md de section (Index de dossier)
- Résumer ce que couvre la section.
- Lister toutes les pages de la section avec des liens relatifs.
Pages de contenu
- Un sujet ciblé par page.
- Commencer par un bref paragraphe d'introduction.
- Utiliser les composants MDX si approprié :
:::note,:::warning,:::tip,:::dangerpour les encarts.- Listes numérotées pour les procédures pas à pas.
- Lier librement aux pages connexes en utilisant des chemins relatifs.
- Terminer par une section « Prochaines étapes » ou « Liés » si utile.
Étape 6 — Diagrammes Mermaid (si nécessaire)
Si la documentation bénéficie de diagrammes (architecture, flux, séquences, diagrammes ER,
machines à états, etc.), intégrez les diagrammes Mermaid en ligne dans les fichiers .md concernés.
Avant de générer un diagramme, lisez
references/rules/mermaid.mdpour la référence complète de la syntaxe et les règles de génération. Toutes les règles de ce fichier sont obligatoires.
Liste de vérification rapide (depuis mermaid.md) :
- Choisir le type de diagramme le plus approprié — ne PAS prendre
flowchartpar défaut. - Toujours déclarer la direction dans les organigrammes :
flowchart TDouflowchart LR. - ID des nœuds : uniquement des lettres, chiffres, underscores. Pas de
-,.,(,). - Les étiquettes de nœud avec des espaces doivent utiliser des guillemets :
A["Mon étiquette"]. - Les sous-graphes doivent avoir des ID explicites :
subgraph monid["Étiquette"]. - Diagrammes de séquence : déclarez toutes les lignes
participantavant les messages. - Pas de couleurs ni de styles codés en dur, sauf si l'utilisateur le demande explicitement.
- Utiliser des émojis au lieu de couleurs pour transmettre un sens sémantique.
- Un diagramme par bloc de code ; valider la syntaxe avant de sortir.
Étape 7 — Créer les fichiers et livrer
Utilisez create_file pour écrire chaque fichier .md dans le système de fichiers. Ensuite, compressez le tout
et appelez present_files pour que l'utilisateur puisse télécharger le résultat.
7.1 Écrire chaque fichier
Pour chaque fichier de la structure planifiée, appelez create_file avec le chemin complet
sous /mnt/user-data/outputs/<nom-du-projet>/ :
/mnt/user-data/outputs/mon-projet/README.md
/mnt/user-data/outputs/mon-projet/01-prise-en-main/README.md
/mnt/user-data/outputs/mon-projet/01-prise-en-main/01-installation.md
...
Écrivez le contenu final complet dans chaque appel — n'écrivez pas d'espaces réservés.
7.2 Compresser et présenter
Une fois tous les fichiers écrits, compressez le dossier de sortie et appelez present_files :
cd /mnt/user-data/outputs
zip -r documentation-mon-projet.zip mon-projet/
Appelez ensuite present_files avec le chemin vers le fichier .zip.
7.3 Résumé dans le chat
Après present_files, écrivez un court message dans le chat contenant :
- Arborescence des fichiers — affichez la structure complète des répertoires qui a été générée.
- Comment servir — une ligne :
npx mdsvr ./mon-projetoumdsvr ./mon-projet. - Nombre de pages — par exemple « 8 pages générées dans 3 sections. »
Référence rapide — Erreurs courantes à éviter
❌ Chemin absolu dans un lien : [Page](/docs/page)
✅ Chemin relatif : [Page](./page)
❌ Extension .md dans un lien : [Page](./page.md)
✅ Pas d'extension : [Page](./page)
❌ Lien vers le fichier README : [Section](./01-section/README)
✅ Lien vers le dossier : [Section](./01-section)
❌ Point dans le nom de fichier : 01.demarrage-rapide.md
✅ Séparateur par trait d'union : 01-demarrage-rapide.md
❌ H1 manquant : ## Introduction (le premier titre est H2)
✅ Commencer par H1 : # Introduction
❌ Niveau de titre sauté : # Titre → ### Sous (saute H2)
✅ Hiérarchie correcte : # Titre → ## Section → ### Sous-section
❌ Pas de frontmatter : (le fichier commence directement par #)
✅ Frontmatter présent : --- title: "..." description: "..." ---
Fichiers de référence
references/rules/mermaid.md— Référence complète de la syntaxe Mermaid v11 pour les 19 types de diagrammes. Lisez ce fichier chaque fois qu'un diagramme est nécessaire dans la documentation.