Édition locale de la doc

Preview Mintlify en local sur http://localhost:3000 avant de pusher.

Cette page concerne l’édition de cette documentation (Mintlify). Pour développer la plateforme SnakySec elle-même, voir Architecture et le repo principal.

Pré-requis

1. Node.js 20+

   node --version doit retourner ≥ 20.0.0. Si pas, installe via Volta ou nvm.

2. Mintlify CLI

   npm install -g mint
   

   mint --version doit retourner ≥ 4.0.0.

3. Repo cloné

   git clone [e-mail]:snakysec-group/mssp-snakysec-multi-tenants.git
   cd mssp-snakysec-multi-tenants/docs
   

Lancer la preview

cd docs
mint dev

Ouvre http://localhost:3000. Le serveur watch les fichiers — toute édition d’un .md ou .mdx rafraîchit la page automatiquement.

Si le port 3000 est pris (la plateforme Next.js tourne dessus en preprod), utilise mint dev --port 3001.

Vérifier les liens cassés

Avant de push, lance :

mint broken-links

Sortie attendue : 0 broken links. Sinon, corrige les liens cassés ou ajuste les chemins dans docs.json.

Modifier docs.json

Le fichier docs/docs.json (schema v4) configure :

• Le branding (logo, couleurs, favicon)
• La navigation (3 tabs : Documentation / Disaster Recovery / Runbooks Ops)
• Les ancres globales (Plateforme, GitLab)
• Le menu contextuel (Copy / ChatGPT / Claude / Cursor / VSCode export)
• La search bar prompt

Toute modification de docs.json doit garder le JSON valide. Tester avec :

python -c "import json; json.load(open('docs.json'))"

Le runtime Mintlify rejette silencieusement un JSON cassé et le build prod fail.

Composants Mintlify utilisés

Card / CardGroup / Columns

Pour les pages d’accueil, regrouper liens visuellement.

Note / Tip / Warning

Callouts colorés. Utiliser parcimonieusement.

Steps / Step

Procédures pas-à-pas (runbooks, quickstart).

Tabs

Alternatives (Mac/Linux/Windows, etc.). Ne pas surcharger.

Réf complète : Mintlify components.

Workflow de contribution

1. Branche feature

   git checkout -b docs/sujet-traité
   
2. Édite + preview

   mint dev ouvert en parallèle, recharge à chaque save.

3. Vérifie

   mint broken-links
   python -c "import json; json.load(open('docs.json'))"
   
4. Commit + push

   git add docs/
   git commit -m "docs(<scope>): <résumé>"
   git push origin docs/sujet-traité
   
5. Merge sur main

   Mintlify déclenche un build automatique sur push to main. Vérifier sur dashboard.mintlify.com onglet Builds.

AI tooling (optionnel)

Pour avoir Claude Code / Cursor / Windsurf alignés avec Mintlify :

npx skills add https://mintlify.com/docs

Ce skill installe les composants reference, writing standards, et workflow guidance. Cf. AGENTS.md pour les conventions SnakySec spécifiques.