--- title: Aperçu du CLI description: Prévisualisez, validez et maintenez votre documentation depuis le terminal. Installez globalement ou exécutez avec npx. --- Le CLI Jamdesk vous permet de prévisualiser la documentation en local, de valider la configuration, de vérifier les liens brisés et de migrer depuis d'autres plateformes. Il est open-source sous la [licence Apache 2.0](https://github.com/jamdesk/jamdesk-cli). ## Installation Installez globalement depuis [npm](https://www.npmjs.com/package/jamdesk) pour utiliser `jamdesk` depuis n'importe où : ```bash npm install -g jamdesk ``` Installez via Homebrew sur macOS ou Linux : ```bash brew tap jamdesk/tap brew install jamdesk ``` Installez via script : ```bash curl -fsSL https://get.jamdesk.com | bash ``` Mise à jour ou désinstallation : ```bash curl -fsSL https://get.jamdesk.com/upgrade | bash curl -fsSL https://get.jamdesk.com/uninstall | bash ``` Installez via script : ```powershell iwr https://get.jamdesk.com/win | iex ``` Mise à jour ou désinstallation : ```powershell iwr https://get.jamdesk.com/upgrade | iex iwr https://get.jamdesk.com/uninstall | iex ``` Exécutez sans installer : ```bash npx jamdesk dev ``` Après l'installation, vérifiez que tout fonctionne : ```bash jamdesk --version ``` ### Prérequis - **Node.js** v20.0.0 ou supérieur - **npm** v8 ou supérieur (recommandé) ## Démarrage rapide Créez un nouveau projet de documentation : ```bash jamdesk init my-docs cd my-docs ``` Lancez le serveur de développement local avec rechargement à chaud : ```bash jamdesk dev ``` Votre documentation sera accessible à l'adresse **http://localhost:3000/docs** Vérifiez les erreurs de configuration, les liens brisés et l'orthographe : ```bash jamdesk validate jamdesk broken-links jamdesk spellcheck ``` ## Commandes Exécutez `jamdesk --help` pour obtenir des informations détaillées sur n'importe quelle commande. ### Développement Démarre le serveur de développement local avec rechargement à chaud. ```bash jamdesk dev jamdesk dev --port 3001 ``` **Fonctionnalités :** - Validation automatique au démarrage (schéma docs.json et syntaxe MDX) - Rechargement à chaud lors des modifications de fichiers MDX - Reconstruction automatique de la navigation lors des modifications de docs.json - CSS personnalisé (`style.css`) rechargé lors de l'actualisation du navigateur - Fonctionnalité de recherche complète - Tous les thèmes et composants disponibles **Options :** | Indicateur | Description | |------|-------------| | `-p, --port ` | Port d'écoute (défaut : 3000) | | `-v, --verbose` | Activer la sortie détaillée | Crée un nouveau projet de documentation. ```bash jamdesk init # Interactive mode jamdesk init my-docs # Create in new directory ``` Cette commande crée un nouveau projet avec : - Le fichier de configuration `docs.json` - Des pages MDX d'exemple - Une structure de dossiers recommandée ### Authentification Connectez-vous à Jamdesk via votre navigateur. Requis avant de déployer. ```bash jamdesk login ``` Ouvre le dashboard Jamdesk dans votre navigateur pour l'authentification. Les identifiants sont stockés localement dans `~/.jamdeskrc`. Flux d'authentification par navigateur, gestion des sessions et dépannage Efface les identifiants stockés. ```bash jamdesk logout ``` Affiche l'utilisateur actuellement authentifié et vérifie que votre session est valide. ```bash jamdesk whoami ``` ### Validation Valide votre configuration `docs.json`, la syntaxe MDX et les spécifications OpenAPI. ```bash jamdesk validate jamdesk validate --skip-mdx ``` **Vérifications effectuées :** - Syntaxe JSON valide dans docs.json - Champs obligatoires (name, navigation) - Valeurs de thème valides - Erreurs de syntaxe MDX (ex. : caractères `<` non échappés) - Validation de la spécification OpenAPI (si configurée) - Conformité au schéma **Options :** | Indicateur | Description | |------|-------------| | `--skip-mdx` | Ignorer la validation de la syntaxe MDX | | `-v, --verbose` | Afficher la sortie de validation détaillée | Exécutez cette commande avant de déployer pour détecter les erreurs en amont. Analyse votre documentation à la recherche de liens internes brisés. ```bash jamdesk broken-links ``` **Exemple de sortie :** ```text docs/getting-started.mdx:15 - /docs/quikstart Did you mean: /docs/quickstart Found 1 broken link in 45 files. ``` Détecte les liens vers des pages manquantes et les fautes de frappe. Voir [Liens et navigation](/fr/content/links#comment-les-liens-internes-sont-d-tect-s) pour plus de détails. Vérifie l'orthographe de votre documentation. ```bash jamdesk spellcheck ``` **Exemple de sortie :** ```text getting-started.mdx:14 - "recieve" └─ Did you mean: receive Found 3 misspellings across 24 pages. Tip: Run "jamdesk spellcheck --fix" to interactively fix or ignore words. ``` Utilise un dictionnaire anglais avec plus de 150 termes techniques intégrés (API, GraphQL, Kubernetes, React, etc.) pour éviter les faux positifs sur le jargon courant. Ignore les blocs de code, le code en ligne, le frontmatter, les balises JSX, les URL et les chemins de fichiers. Actuellement en anglais uniquement — la prise en charge de dictionnaires multilingues est prévue. **Options :** | Indicateur | Description | |------|-------------| | `--fix` | Corriger les fautes de manière interactive ou les ajouter à la liste d'exclusion | | `--json` | Sortie au format JSON (pour les pipelines CI) | | `-v, --verbose` | Afficher chaque fichier au fur et à mesure de la vérification | **Mode de correction interactive (`--fix`)** : traite chaque mot mal orthographié unique : ```text 1/10 "recieve" — found in 3 files intro.mdx:14, setup.mdx:7, guide.mdx:22 ? What do you want to do? ❯ Fix → receive (recommended) Fix → relieve Ignore in the future (add to docs.json) Skip ``` - **Fix** remplace le mot par une suggestion dans tous les fichiers (sans modifier les blocs de code ni les attributs JSX). Jusqu'à 3 suggestions sont affichées, la meilleure correspondance étant marquée comme recommandée. - **Ignore** ajoute le mot à `spellcheck.ignore` dans votre docs.json pour qu'il ne soit plus signalé - **Skip** ne fait rien pour cette exécution Les modifications sont prévisualisées et confirmées avant d'être appliquées. **Liste d'exclusion personnalisée :** Ajoutez des termes spécifiques à votre projet dans votre docs.json : ```json docs.json { "spellcheck": { "ignore": ["YourProduct", "kubectl", "Terraform"] } } ``` Le nom de votre projet tiré de `docs.json` est automatiquement ignoré. Valide un fichier de spécification OpenAPI unique. ```bash jamdesk openapi-check openapi.yaml jamdesk openapi-check api/spec.json ``` **Validations effectuées :** - Syntaxe YAML/JSON valide - Conformité au schéma OpenAPI 3.x - Définitions des endpoints - Les références `$ref` se résolvent correctement ### Gestion des fichiers Renomme une page et met automatiquement à jour toutes les références. ```bash jamdesk rename docs/old-name.mdx docs/new-name.mdx ``` **Cette commande effectue les actions suivantes :** - Renommer le fichier - Mettre à jour la navigation dans docs.json - Mettre à jour les liens dans tous les autres fichiers MDX - Mettre à jour les références aux extraits Utilisez cette commande plutôt qu'un renommage manuel pour maintenir toutes les références synchronisées. ### Migration Migre la documentation de Mintlify vers Jamdesk. ```bash jamdesk migrate ``` Détecte votre configuration Mintlify et la convertit au format Jamdesk. En une seule passe, renomme les composants dépréciés (ex. : `CardGroup` → `Columns`), déplace les fichiers MDX d'extraits orphelins dans `/snippets/` et réécrit les imports relatifs au parent, extrait les composants en ligne utilisant des hooks React dans `/snippets/.tsx` avec `'use client'`, et corrige automatiquement les problèmes mécaniques de syntaxe MDX. Idempotente — réexécutez-la sans risque. Guide de migration complet avec instructions pas à pas pour Mintlify et autres plateformes ### Déploiement Téléverse votre documentation et déclenche un build directement depuis le terminal. ```bash jamdesk deploy jamdesk deploy --detach jamdesk deploy --full-rebuild ``` La progression s'affiche en temps réel à mesure que chaque phase du build se termine. Également disponible sous la forme `jamdesk push`. | Indicateur | Description | |------|-------------| | `--detach` | Mettre en file d'attente et quitter immédiatement | | `--full-rebuild` | Forcer un build complet (sans cache) | | `--project ` | Déployer vers un projet spécifique | Pipeline de déploiement complet, phases de build, référence des erreurs et dépannage ### Maintenance Vérifie votre environnement et diagnostique les problèmes. ```bash jamdesk doctor ``` **Vérifications :** - Version de Node.js (requiert v20+) - Version de npm - Existence et validité du fichier docs.json - État du cache ~/.jamdesk - Permissions d'écriture Exécutez cette commande si vous rencontrez des problèmes avec le CLI. Vide le répertoire de cache ~/.jamdesk. ```bash jamdesk clean ``` Cette commande supprime les dépendances en cache et les artefacts de build. Utilisez-la pour : - Libérer de l'espace disque - Corriger les problèmes de cache corrompu - Forcer une nouvelle installation des dépendances Les dépendances seront réinstallées lors du prochain `jamdesk dev`. Met à jour le CLI vers la dernière version. ```bash jamdesk update ``` Vous pouvez également mettre à jour manuellement : ```bash npm update -g jamdesk ``` ## Configuration Créez `~/.jamdeskrc` pour définir les options par défaut : ```json { "defaultPort": 3001, "verbose": false, "checkUpdates": true } ``` | Option | Type | Défaut | Description | |--------|------|---------|-------------| | `defaultPort` | number | 3000 | Port par défaut du serveur de développement | | `verbose` | boolean | false | Activer la sortie détaillée par défaut | | `checkUpdates` | boolean | true | Vérifier les mises à jour du CLI au démarrage | ## Dépannage Les fichiers MDX sont analysés comme du JSX, certains caractères ont donc une signification particulière. **Problème courant :** Le caractère `<` est interprété comme le début d'une balise JSX. ```text ✗ Found 1 MDX syntax error(s) getting-started.mdx:42 Unexpected character `5` (U+0035) before name Fix: A < character is being parsed as JSX. Use < or rewrite ``` **Solutions :** - Utilisez `<` pour le signe inférieur littéral : `Values <50% are low` - Réécrivez pour éviter le caractère : `"Below 50%"` à la place de `"<50%"` - Exécutez `jamdesk validate` pour des messages d'erreur détaillés avec les numéros de ligne Assurez-vous d'être dans un répertoire contenant un fichier `docs.json`. **Solutions :** - Exécutez `jamdesk init` pour créer un nouveau projet - Vérifiez que vous êtes dans le bon répertoire - Confirmez que le fichier est nommé exactement `docs.json` (pas `doc.json` ou autre) Le serveur de développement peut ne pas démarrer pour plusieurs raisons. **Essayez ces étapes :** 1. Exécutez `jamdesk doctor` pour vérifier votre environnement 2. Exécutez `jamdesk clean` pour vider le cache 3. Utilisez `jamdesk dev --verbose` pour une sortie d'erreur détaillée 4. Vérifiez que Node.js v20+ est installé : `node --version` Le premier lancement installe les dépendances dans `~/.jamdesk/node_modules`. C'est normal et ne se produit qu'une seule fois. Les lancements suivants seront beaucoup plus rapides. Un autre processus utilise le port par défaut. **Solutions :** ```bash # Use a different port jamdesk dev --port 3001 # Or set a default in ~/.jamdeskrc { "defaultPort": 3001 } ``` Il est possible que vous n'ayez pas les permissions d'écriture sur le répertoire de cache. **Solutions :** 1. Vérifiez les permissions sur `~/.jamdesk` : `ls -la ~/.jamdesk` 2. Corrigez le propriétaire : `sudo chown -R $(whoami) ~/.jamdesk` 3. Exécutez `jamdesk clean` et réessayez **Problème persistant ?** Consultez le [guide de dépannage CLI](/fr/help/troubleshooting/cli-issues) ou [ouvrez un ticket sur GitHub](https://github.com/jamdesk/jamdesk-cli/issues). ## Prochaines étapes Flux de connexion, sessions et dépannage Déployer depuis le terminal Options avancées de développement local Migrer depuis Mintlify ou d'autres plateformes