Commandes CLI

DocAnvil propose six sous-commandes : new, theme, doctor, serve, build, et export.

Options globales

docanvil new

Crée un nouveau projet de documentation.

docanvil new <nom>

Crée un répertoire de projet avec :

• docanvil.toml — configuration du projet
• nav.toml — structure de navigation
• docs/ — répertoire de contenu avec des pages de démarrage
• theme/custom.css — feuille de style personnalisée vide

# Créer un projet de docs
docanvil new mes-docs

# Créer et immédiatement lancer le serveur
docanvil new mes-docs && cd mes-docs && docanvil serve

docanvil theme

Génère interactivement un thème de couleurs personnalisé pour votre projet.

docanvil theme [--overwrite] [--path <rép>]

La commande guide à travers un prompt interactif :

1. Mode de couleur — choisir Clair uniquement, Sombre uniquement, ou Les deux (clair + sombre avec bascule)
2. Couleur primaire — code hex pour la couleur d'accent principale (demandé une fois par mode)
3. Couleur secondaire — code hex pour la couleur d'avertissement/secondaire (demandé une fois par mode)

Elle dérive ensuite toutes les variables CSS liées aux couleurs, les écrit dans theme/custom.css, et met à jour docanvil.toml avec custom_css et color_mode.

Si des personnalisations de thème existantes sont détectées (custom_css ou [theme.variables] dans la configuration), la commande se termine avec un message utile à moins que --overwrite ne soit passé.

# Générer un thème pour le projet courant
docanvil theme

# Générer un thème pour un projet dans un autre répertoire
docanvil theme --path ../mes-docs

# Remplacer un thème existant
docanvil theme --overwrite

Modes de couleur

Quand "Les deux" est sélectionné, vous êtes invité à saisir des couleurs primaires et secondaires distinctes pour chaque mode, permettant des palettes claires et sombres indépendantes.

Variables dérivées (clair)

À partir des deux couleurs saisies, les variables CSS suivantes sont générées pour le mode clair :

Variables dérivées (sombre)

Le mode sombre utilise une logique de dérivation inversée plus des couleurs d'arrière-plan et de texte explicites :

docanvil doctor

Diagnostique les problèmes de configuration et de contenu du projet avant la compilation.

docanvil doctor [--fix] [--strict] [--format <fmt>] [--path <rép>]

# Vérifier le projet courant
docanvil doctor

# Vérifier et corriger automatiquement les problèmes sûrs
docanvil doctor --fix

# Utiliser en CI pour échouer sur tout problème
docanvil doctor --strict

# Vérifier un projet dans un autre répertoire
docanvil doctor --path ../mes-docs

Si aucun docanvil.toml n'est trouvé, doctor affiche un message amical suggérant docanvil new et se termine proprement.

Sortie lisible par les machines

L'option --format bascule de la sortie colorée par défaut vers du XML structuré, utile pour l'intégration avec des outils d'annotation CI ou des rapporteurs de tests. La sortie lisible par les machines est écrite sur stdout ; les messages de progression sont entièrement supprimés.

# Sortie Checkstyle XML (ex. pipe vers reviewdog)
docanvil doctor --format checkstyle

# Sortie JUnit XML (ex. pour le résumé de tests GitHub Actions)
docanvil doctor --format junit

# Échouer en CI et émettre du Checkstyle XML
docanvil doctor --format checkstyle --strict

# Sauvegarder les résultats JUnit dans un fichier
docanvil doctor --format junit > test-results/doctor.xml

Checkstyle XML regroupe les diagnostics par fichier. Chaque élément <error> porte :

• severity — info, warning, ou error
• message — le message de diagnostic
• line — numéro de ligne source (0 quand non applicable)
• source — docanvil.{catégorie}.{vérification} (ex. docanvil.readability.long-paragraph)

JUnit XML mappe chaque catégorie de vérification à un <testsuite>. Les huit catégories sont toujours émises — les catégories sans problème produisent un seul <testcase name="all-checks-passed"/> réussi. Les avertissements et erreurs apparaissent comme éléments <failure> ; les diagnostics info apparaissent comme <skipped/>.

Catégories de vérifications

Doctor exécute six catégories de vérifications, jusqu'à huit quand le versionnement et/ou l'i18n sont activés :

1. Structure du projet — fichier de configuration, répertoire de contenu, page index
2. Configuration — analyse TOML, références de fichiers (logo, favicon), validation nav.toml
3. Thème — existence du fichier CSS personnalisé, syntaxe Tera du template de mise en page
4. Contenu — wiki-links cassés, directives non fermées, erreurs JSON dans le front matter, slugs dupliqués
5. Lisibilité — vérifications de qualité du contenu sur tous les fichiers Markdown sources (voir ci-dessous)
6. Versions (versionnement uniquement) — configuration des versions et intégrité des répertoires
7. Traductions (i18n uniquement) — couverture des traductions dans les locales activées
8. Sortie — accessibilité en écriture du répertoire de sortie

Vérifications de lisibilité

Ces vérifications s'exécutent sur les sources Markdown brutes et détectent les problèmes de qualité du contenu avant qu'ils n'atteignent les lecteurs. Chaque diagnostic inclut le chemin du fichier et le numéro de ligne.

Structure des titres

Liens et images

Blocs de code

Qualité du texte

Toutes les vérifications ignorent le contenu à l'intérieur des blocs de code délimités. La plupart suppriment aussi les spans de code inline avant l'analyse pour éviter les faux positifs.

Vérifications des versions

Ces vérifications s'exécutent quand version.enabled est non vide dans docanvil.toml.

Correction automatique

L'option --fix applique des corrections sûres et non destructives :

Les problèmes de lisibilité ne sont jamais corrigés automatiquement — ils nécessitent un jugement humain.

docanvil serve

Démarre un serveur de développement avec rechargement en direct.

docanvil serve [--host <adresse>] [--port <port>] [--path <rép>]

Le serveur :

• Compile le site au démarrage
• Surveille tous les fichiers du projet pour les modifications (Markdown, TOML, CSS, templates)
• Recompile les pages affectées lors d'un changement de fichier
• Notifie le navigateur via WebSocket à /__docanvil_ws
• Le navigateur recharge automatiquement — pas besoin de rafraîchissement manuel

# Par défaut : localhost:3000
docanvil serve

# Hôte et port personnalisés
docanvil serve --host 0.0.0.0 --port 8080

# Sortie détaillée pour voir les événements de recompilation
docanvil serve --verbose

# Servir un projet depuis un autre répertoire
docanvil serve --path ../mes-docs

docanvil build

Génère le site HTML statique pour le déploiement.

docanvil build [--out <chemin>] [--clean] [--path <rép>]

Le pipeline de compilation traite chaque page en passant par :

1. Expansion des directives (composants)
2. Conversion des popovers
3. Rendu Markdown (comrak avec GFM)
4. Résolution des wiki-links
5. Injection des attributs inline
6. Encapsulation de template (mise en page Tera)

Les ressources statiques (CSS personnalisé, images) sont copiées dans le répertoire de sortie.

# Compilation par défaut vers dist/
docanvil build

# Compilation propre vers un répertoire personnalisé
docanvil build --out public --clean

# Compiler un projet depuis un autre répertoire
docanvil build --path ../mes-docs

docanvil export

Exporte votre documentation dans d'autres formats.

docanvil export pdf

Exporte les docs en un seul PDF en utilisant Chrome ou Chromium.

docanvil export pdf --out <chemin> [--path <rép>] [--locale <code>]

Nécessite Chrome ou Chromium. DocAnvil recherche dans les emplacements d'installation courants sur macOS, Windows et Linux avant de chercher dans le PATH.

# Exporter le projet courant
docanvil export pdf --out guide.pdf

# Exporter une seule locale
docanvil export pdf --out guide-fr.pdf --locale fr

# Exporter toutes les locales activées (projets i18n)
docanvil export pdf --out guide.pdf --locale all

# Exporter un projet dans un autre répertoire
docanvil export pdf --out guide.pdf --path ../mes-docs

La sortie PDF est configurée via la section [pdf] dans docanvil.toml. Consultez Export PDF pour le guide complet, y compris les pages de couverture, les formats de papier, le support RTL, et le CSS personnalisé.

Codes de sortie

Toutes les commandes retournent des codes de sortie structurés pour que les pipelines CI puissent distinguer les différents types d'échec :

Vous pouvez utiliser ces codes dans les scripts CI pour gérer différents types d'échec de manière appropriée :

docanvil build --strict
code=$?
case $code in
  0) echo "Compilation réussie" ;;
  2) echo "Corrigez votre docanvil.toml" ;;
  3) echo "Problèmes de contenu trouvés — vérifiez les avertissements ci-dessus" ;;
  *) echo "Compilation échouée avec le code $code" ;;
esac

Pages associées

• Installation — installer et créer votre premier projet
• Configuration — référence docanvil.toml et nav.toml
• Export PDF — pages de couverture, formats de papier, support RTL, et export par locale