Publier et exporter

Build VitePress

Le bouton Build docs lance la commande configurée côté serveur. Le build prépare les pages Markdown, normalise les médias, copie les uploads, puis produit le dossier :

./docs/.vitepress/dist

Le build reste volontairement explicite : l’édition Markdown ne relance pas VitePress à chaque frappe.

Export ZIP — projet VitePress source recommandé

L’export Projet VitePress source est le choix prioritaire. Il produit une archive réutilisable comme projet VitePress autonome.

Il contient les pages Markdown, les uploads, la configuration VitePress générée et un package.json minimal pour reconstruire la documentation hors de l’application NFZ.

Structure attendue :

.
├─ .github
│  └─ workflows
│     └─ deploy-vitepress-docs.yml
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

Dans le projet exporté :

bun install
bun run docs:dev
bun run docs:build
bun run docs:preview

Le fichier docs/.vitepress/config.js est généré à partir de la configuration pilotée par NFZ. Il conserve la navigation, le sidebar, les libellés, le footer et les options principales VitePress.

Déploiement GitHub Pages avec Node 24

L’archive Projet VitePress source embarque un workflow GitHub Actions prêt à l’emploi :

.github/workflows/deploy-vitepress-docs.yml

Ce workflow :

• utilise Node.js 24 via actions/setup-node@v6 ;
• installe Bun 1.3.6 via oven-sh/setup-bun@v2 ;
• lance bun run docs:build ;
• publie docs/.vitepress/dist avec GitHub Pages ;
• garde FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true pour détecter rapidement les actions incompatibles avec Node 24.

Avant le premier déploiement :

1. pousser le projet exporté sur GitHub ;
2. ouvrir Settings → Pages ;
3. choisir Build and deployment → Source → GitHub Actions ;
4. définir éventuellement la variable de dépôt VITEPRESS_BASE :
   • /<nom-du-repo>/ pour un dépôt publié sous https://user.github.io/nom-du-repo/ ;
   • / pour un domaine personnalisé ou un site utilisateur/organisation.

Sans variable VITEPRESS_BASE, le workflow utilise automatiquement /<nom-du-repo>/.

Publication GitHub Pages du guide utilisateur de l’application

Dans le dépôt applicatif nfz-docs-notion-editor, le workflow racine .github/workflows/deploy-vitepress-docs.yml publie maintenant le guide utilisateur public, et non la documentation technique /docs.

Il surveille :

user-guide/**
.github/workflows/deploy-vitepress-docs.yml
package.json
bun.lock
bun.lockb

Il exécute :

bun run guide:build

Puis publie :

user-guide/.vitepress/dist

La configuration user-guide/.vitepress/config.ts utilise process.env.VITEPRESS_BASE || '/guide/', ce qui permet de conserver /guide/ en local tout en utilisant automatiquement /<nom-du-repo>/ sur GitHub Pages via la variable VITEPRESS_BASE du workflow.

Export ZIP — site buildé

L’export Site buildé statique archive le contenu de docs/.vitepress/dist.

C’est le bon format pour :

• livrer une version figée à publier immédiatement ;
• archiver une version validée ;
• déployer sur un hébergement statique ;
• fournir une preuve de publication.

Structure attendue après extraction :

.
├─ index.html
├─ assets/
├─ guide/
├─ uploads/
└─ ...

Bonnes pratiques avant export

• Sauvegarder la page Markdown.
• Lancer Build docs.
• Ouvrir /docs/ et vérifier le rendu public.
• Contrôler les liens, les images et les vidéos YouTube.
• Utiliser Projet VitePress source en priorité pour transmettre une base modifiable, versionnable et exploitable commercialement.
• Utiliser Site buildé statique pour publier rapidement une version figée.

Vérifications avant livraison

• La page /docs/ affiche bien le hero.
• Les liens de navigation fonctionnent.
• Les images ne pointent pas vers /docs/docs/....
• Les images inline base64 ont été converties vers /docs/uploads/....
• Les vidéos YouTube sont normalisées en iframe youtube-nocookie compatible VitePress.
• L’export ZIP contient la structure attendue selon le mode choisi.