Documentation

Appearance

Site de doc — lancement & troubleshooting ​

Comment lancer le site de documentation (ce site VitePress) en local, et les pièges qu'on rencontre en essayant. Même format que les autres pages de troubleshooting : symptôme, cause, fix, pourquoi.

Le site vit dans documentation/ à la racine du repo. C'est un projet VitePress — Vite + Vue + Markdown — qui build un site statique à partir des fichiers .md sous guide/en/ et guide/fr/.

Référence rapide ​

Depuis le dossier documentation/ :

bash
npm install            # une fois, pour installer VitePress
npm run docs:dev       # serveur de dev local avec hot reload — http://localhost:5173
npm run docs:build     # build statique vers .vitepress/dist/
npm run docs:preview   # sert le build de prod en local

Règle d'usage : utilise docs:dev pendant que tu écris — c'est tolérant et rapide. Lance docs:build avant de pousser — il attrape les liens morts et autres erreurs que docs:dev ignore.

1. docs:build échoue avec Found dead link(s) ​

Symptôme ​

(!) Found dead link ./../../VPS_SETUP in file guide\en\docker-vps-migration.md
(!) Found dead link ./../../VPS_SECURITY in file guide\en\docker-vps-migration.md
...
x Build failed in 1.48s
build error:
[vitepress] 8 dead link(s) found.

Le serveur de dev (docs:dev) fonctionne très bien sur les mêmes fichiers. Seul docs:build plante.

Cause ​

VitePress résout chaque lien markdown au moment du build. Si la cible d'un lien relatif n'existe pas sur le disque — même un lien vers un fichier en dehors de l'arbre documentation/ — le build échoue. Le serveur de dev n'applique pas ce check.

Le piège : des liens du genre [VPS_SETUP.md](../../VPS_SETUP.md) sont écrits en supposant que le fichier vit à la racine du repo (snag-tcg/VPS_SETUP.md). Si ces fichiers à la racine n'ont jamais été commit (ou ont été déplacés), le build casse alors que le markdown se lit très bien.

Fix — 3 options, par ordre de préférence ​

(a) Supprimer ou repointer le lien (propre, quand la cible n'existe vraiment pas)

Remplace le lien par du texte simple, ou repointe-le vers une page qui existe dans documentation/. C'est la bonne réponse quand le fichier lié n'a jamais été commit.

(b) Créer le fichier manquant (quand le lien est censé exister)

Si VPS_SETUP.md devait vivre à la racine du repo et a été perdu, restaure-le. Pas de stub vide pour faire semblant — les stubs vides pourrissent.

(c) Désactiver le check globalement (dernier recours)

Dans documentation/.vitepress/config.mjs :

js
export default defineConfig({
  // ...
  ignoreDeadLinks: true,
})

Tu peux aussi passer un tableau de patterns pour ignorer certains liens morts plutôt que tous. N'y va pas en premier réflexe — ça cache la pourriture de liens dans tout le reste de la doc.

Pourquoi ​

Le check des liens morts est un des rares endroits où VitePress valide le contenu plutôt que de juste le rendre. Le désactiver sans réfléchir transforme une erreur de build aujourd'hui en "tous les liens du site sont cassés" trois mois plus tard. Répare le lien, pas le check.

2. Le build affiche The language 'caddy' is not loaded, falling back to 'txt' ​

Symptôme ​

The language 'caddy' is not loaded, falling back to 'txt' for syntax highlighting.

Le build réussit quand même (sauf s'il échoue pour une autre raison) ; le bloc de code s'affiche juste sans coloration syntaxique.

Cause ​

VitePress utilise Shiki pour la coloration syntaxique. Shiki ne connaît que les langages qu'il embarque par défaut. caddy (et quelques autres grammaires de niche) n'en font pas partie — quand un bloc est taggué ```caddy, Shiki ne sait pas le colorer et tombe en texte brut.

Fix ​

Deux options :

(a) Retagger le bloc avec un langage proche que Shiki connaît :

markdown
```nginx
# Contenu du Caddyfile ici
```

Pour les Caddyfile, nginx est le remplaçant habituel — la structure directive/valeur est suffisamment proche pour que les couleurs ne soient pas franchement fausses.

(b) Enregistrer le langage explicitement dans .vitepress/config.mjs via le hook markdown.shikiSetup. Plus de boulot, à ne faire que si tu as beaucoup de snippets Caddyfile.

Pourquoi ​

C'est un warning, pas une erreur — laisser tel quel est OK tant que le bloc non-coloré ne te dérange pas. On le mentionne ici parce qu'il apparaît dans la sortie du build à côté de vraies erreurs, ce qui rend la sortie plus inquiétante qu'elle ne l'est.

3. docs:dev affiche Port 5173 is in use, trying another one... ​

Symptôme ​

  vitepress v1.6.4

  ➜  Local:   http://localhost:5174/

Le port a glissé de 5173 vers 5174 (ou plus).

Cause ​

Un autre process Vite est déjà bind sur 5173 — typiquement un docs:dev ou un npm run dev du projet frontend oublié dans un autre terminal.

Fix ​

Soit tu utilises le nouveau port choisi par VitePress (il te le dit en sortie), soit tu libères 5173 :

bash
# trouver et tuer ce qui retient le port
lsof -i :5173       # macOS/Linux
ss -ltnp | grep 5173  # alternative Linux

# Windows (PowerShell)
Get-NetTCPConnection -LocalPort 5173

Pourquoi ​

Vite incrémente automatiquement le port pour que docs:dev ne soit pas bloquant. Aucun mal à tourner sur 5174 — ça ne vaut le coup de chasser le port que si t'as des bookmarks ou un script hardcodé sur 5173.

4. Entrée de sidebar manquante pour une nouvelle page ​

Symptôme ​

Tu as ajouté guide/fr/ma-nouvelle-page.md, le serveur de dev la prend en compte, mais elle n'apparaît pas dans la sidebar à gauche.

Cause ​

VitePress ne découvre pas automatiquement les entrées de sidebar. Chaque page a besoin d'une entrée dans .vitepress/config.mjs. Le fichier seul suffit à ce que la page s'affiche (l'URL directe fonctionne), mais pas à ce qu'elle apparaisse dans la navigation.

Fix ​

Édite .vitepress/config.mjs et ajoute la page sous la bonne section des sidebars EN et FR :

js
{
  text: 'Infrastructure',
  items: [
    // ...
    { text: 'Ma nouvelle page', link: '/guide/fr/ma-nouvelle-page' }
  ]
}

Refais l'entrée en miroir côté /guide/en/ pour garder la structure bilingue synchrone.

Pourquoi ​

Les entrées de sidebar manuelles sont une feature, pas un bug — elles nous laissent ordonner les pages et les grouper sémantiquement (Infrastructure, Scan, etc.) plutôt que de balancer tous les fichiers par ordre alphabétique. Le coût c'est de penser à l'ajout en deux étapes : créer le fichier et l'enregistrer.