Qu'est-ce que Mintlify Docs et comment l'utiliser : Guide du débutant

Avez-vous du mal à créer une documentation élégante et conviviale qui ne ressemble pas à une corvée ? Dites bonjour à Mintlify, la plateforme native de l’IA qui rend la création de documents époustouflants aussi simple que l’écriture d’un article de blog. Avec plus de 28 000 étoiles sur GitHub et des clients comme Stripe, Mintlify propose des fonctionnalités interactives, des outils d’IA et des intégrations transparentes pour améliorer votre jeu de documentation. Dans ce guide du débutant, je vous guiderai à travers l’installation de Mintlify, la configuration d’un domaine personnalisé, l’exploitation de l’ingestion de l’IA, l’intégration d’un serveur MCP, l’ajout de traductions et l’utilisation d’OpenAPI pour la documentation de l’API. Que vous soyez développeur ou chef d’équipe, vous expédierez des documents de niveau professionnel en un rien de temps. Prêt à rendre la documentation amusante ? Plongeons-nous !

💡

Avant de commencer, si vous cherchez à rationaliser le développement de votre API, Apidog propose une plateforme tout-en-un pour la conception, les tests et la documentation des API. Avec son interface intuitive et ses fonctionnalités robustes, il est parfait pour les débutants comme pour les développeurs chevronnés. Mieux encore, vous pouvez commencer gratuitement ! (apidog)

button

Qu’est-ce que Mintlify ? Votre super-pouvoir de documentation

Mintlify est une plateforme de documentation moderne qui aide les développeurs à créer des documents magnifiques, interactifs et optimisés pour le référencement avec un minimum d’efforts. Conçue pour les équipes et les projets open source, elle convertit les fichiers Markdown et MDX en pages réactives, prend en charge l’intégration de GitHub et propose des fonctionnalités basées sur l’IA, telles que la génération de code et les traductions. Les principaux avantages sont les suivants :

Éditeur WYSIWYG : Modifiez les documents dans une interface basée sur un navigateur.
Composants interactifs : Ajoutez des onglets, des extraits de code et des aires de jeux d’API.
Optimisation de l’IA : Améliorez la recherche et l’accessibilité grâce à l’ingestion de l’IA.
Personnalisable : Ajustez les thèmes, les polices et la navigation via un fichier docs.json.

Avec un flux de travail par glisser-déposer et des taux de conversion utilisateur supérieurs de 40 %, Mintlify est parfait pour les startups ou les projets publics. Configurons-le

Installation et configuration de Mintlify

Démarrer avec Mintlify est un jeu d’enfant, et vous aurez besoin de Node.js, de la CLI Mintlify et d’un compte GitHub. Voici comment démarrer, en fonction du guide officiel.

1. Installer les prérequis :

Node.js : Téléchargez la version 16.6 ou supérieure à partir de https://nodejs.org/. Vérifiez avec node -v.
Compte GitHub : Inscrivez-vous sur github.com si vous ne l’avez pas déjà fait.
VS Code : Facultatif mais recommandé pour l’édition. Obtenez-le à partir de code.visualstudio.com.

2. Cloner le Starter Kit :

Dans votre terminal, clonez le Mintlify Starter Kit :

git clone https://github.com/mintlify/starter-kit
cd starter-kit

Cela crée un projet avec un dossier docs contenant des fichiers MDX et un fichier docs.json pour les paramètres.

3. Installer la CLI Mintlify :

Installez la CLI globalement :

npm install -g mintlify-cli

Vérifiez avec mintlify-cli --version (par exemple, mintlify-cli version 3.1.25).

4. Exécuter l’aperçu local :

Dans le dossier starter, démarrez le serveur de développement :

mintlify-cli dev

Cela ouvre un aperçu à l’adresse http://127.0.0.1:3000. Si le port 3000 est occupé, il essaie 3001 ou utilise --port 3333 pour personnaliser (par exemple, mintlify-cli dev --port=3333).

5. Modifier vos documents :

Ouvrez le projet dans VS Code (code .).
Accédez à docs/introduction.mdx et modifiez le champ « title » en « Bienvenue dans mes documents ! » Enregistrez, et l’aperçu se met à jour instantanément.
Explorez docs.json pour ajuster les polices, les couleurs ou activer le mode sombre. Par exemple :

{
  "name": "My Docs",
  "theme": "prism",
  "colors": { "primary": "#3498db" }
}

Consultez https://mintlify.com/docs pour les paramètres globaux tels que les icônes ou les logos.

J’ai configuré cela en moins de 10 minutes et j’avais un site en direct avec mes ajustements, super fluide !

Configuration d’un domaine personnalisé pour Mintlify

Vous souhaitez que vos documents soient hébergés sur docs.yourcompany.com au lieu d’un sous-domaine mintlify.app ? Mintlify facilite les domaines personnalisés.

1. Accéder aux paramètres :

Connectez-vous à votre tableau de bord Mintlify à l’adresse mintlify.com.
Accédez à Paramètres > Domaine personnalisé.

2. Ajouter votre domaine :

Saisissez votre domaine (par exemple, docs.yourcompany.com).
Suivez les instructions DNS de votre fournisseur (par exemple, Namecheap, GoDaddy) :
Ajoutez un enregistrement CNAME : docs → cname.vercel-dns.com.
Pour Cloudflare, activez la sécurité HTTPS « full strict ».
Si vous utilisez Vercel, ajoutez un enregistrement de vérification TXT (affiché dans le tableau de bord).

3. Attendre la propagation :

Les modifications DNS prennent jusqu’à 48 heures, mais se résolvent souvent plus rapidement. Vérifiez votre domaine dans un navigateur pour confirmer.

J’ai configuré un domaine personnalisé pour un site de test, et il était en ligne en quelques heures, des vibrations professionnelles tout le long !

Tirer parti de l’ingestion de l’IA avec Mintlify

L’ingestion de l’IA de Mintlify rend vos documents plus intelligents et plus accessibles, permettant aux utilisateurs de rechercher du contenu via des requêtes basées sur l’IA.

1. Activer l’ingestion de l’IA :

Dans le tableau de bord Mintlify, accédez à Produits > Chat IA.
Activez l’ingestion de l’IA. Cela indexe vos documents pour la recherche par IA sans configuration supplémentaire.
Mintlify génère automatiquement un sitemap /llms.txt pour que les LLM indexent votre contenu efficacement.

2. Tester la recherche par IA :

Dans vos documents en direct, utilisez la barre de recherche ou le chat IA (s’il est activé via docs.json).
Demandez : « Comment puis-je m’authentifier auprès de l’API ? » L’IA extrait les sections pertinentes, comme votre page d’authentification.

3. Améliorer avec les corrections de l’IA :

Dans l’éditeur Web, l’IA suggère des corrections de syntaxe pour les erreurs MDX (par exemple, des composants mal formés). Activez ceci dans Paramètres > Éditeur.

J’ai essayé la recherche par IA sur un site d’exemple, et elle a trouvé mes documents d’API instantanément, beaucoup plus rapidement que la navigation manuelle !

Intégration d’un serveur MCP avec Mintlify

Le protocole de contexte de modèle (MCP) permet aux applications d’IA d’interagir avec vos documents ou vos API. Mintlify génère un serveur MCP pour relier votre contenu aux LLM.

1. Installer la CLI MCP :

Exécutez :

npm i @mintlify/mcp

Dans le tableau de bord Mintlify, accédez à Produits > Serveur MCP pour obtenir votre commande d’installation unique.

2. Configurer le serveur MCP :

Trouvez votre clé d’administrateur externe et votre clé d’API de chat dans Paramètres > Clés d’API.
Exécutez la commande CLI à partir du tableau de bord, en saisissant les clés lorsque vous y êtes invité.
Activez Accès OpenAPI pour inclure les points de terminaison de l’API (nécessite une spécification OpenAPI).

3. Utiliser le serveur MCP :

La CLI affiche une commande pour démarrer votre serveur (par exemple, npm --prefix ~/.mcp/mintlify start).
Testez avec un client MCP comme Windsurf, en interrogeant : « Rechercher dans mes documents l’authentification de l’API. » Le serveur renvoie des résultats structurés.

Installation du serveur MCP Mintlify localement

Pour exécuter le serveur MCP Mintlify sur votre machine :

Exécutez :

npx @mintlify/mcp add mintlify

Ignorez l’invite de jeton porteur en appuyant sur Entrée.
Sélectionnez votre client MCP (par exemple, Claude Desktop, Windsurf) qui est installé localement.
Le serveur s’installe et se configure pour votre client choisi.

Exemple : J’ai utilisé Windsurf, et le terminal m’a donné :

node C:\User\Me.mcp\mintlify\src\index.js

Exécutez cette commande, cliquez sur l’icône des outils dans votre client et vérifiez que le serveur est disponible.
Vous pouvez également, dans le tableau de bord Mintlify, accéder à Serveur MCP pour trouver une commande permettant d’ajouter le serveur à votre client MCP (par exemple, Apple DB).

Exemple d’invite (dans Windsurf) :

Écrivez un document d’aide sur cette fonctionnalité basé sur ce PRD, dans le style et le ton des documents AppleDB.

Ou, pour le format compatible avec Mintlify :

Écrivez ceci en markdown en utilisant des composants Mintlify comme des ancres.

Copiez la sortie de votre client mcp (par exemple, windsurf ou claude desktop), collez-la dans l’éditeur Web de Mintlify, passez en mode visuel et prévisualisez !

J’ai configuré un serveur MCP, et il a permis à mon assistant IA d’interroger mes documents comme un pro, des trucs futuristes !

Ajout de traductions aux documents Mintlify

Vous souhaitez que vos documents soient disponibles en plusieurs langues ? Les traductions basées sur l’IA de Mintlify facilitent la localisation.

1. Activer les traductions :

Dans le tableau de bord Mintlify, accédez à Paramètres > Traductions.
Ajoutez une langue (par exemple, es pour l’espagnol) et sélectionnez une version à traduire.
Mintlify traduit automatiquement vos documents, en synchronisant les mises à jour avec la version principale.

2. Personnaliser les traductions :

Modifiez les fichiers MDX traduits dans le dossier de langue de votre référentiel (par exemple, docs/es/).
Le contenu fixe tel que « Cette page a-t-elle été utile ? » s’adapte automatiquement à la langue.

3. Tester la traduction :

Dans vos documents en direct, changez de langue via le menu déroulant de version (configuré dans docs.json).

Vérifiez que les titres et le contenu reflètent la langue cible (par exemple, « ¡Bienvenidos ! » pour l’espagnol).

J’ai ajouté des traductions en espagnol, et mes documents étaient prêts à l’échelle mondiale en quelques minutes, une énorme victoire pour l’accessibilité !

Utilisation de Mintlify avec VS Code

Documenter le code dans VS Code ? L’extension de Mintlify facilite les choses !

1. Installer l’extension Mintlify :

Ouvrez la place de marché des extensions de VS Code.
Recherchez « Mintlify » et cliquez sur Installer.

2. Générer de la documentation :

Mettez en surbrillance le code que vous souhaitez documenter.
Cliquez sur l’icône Mintlify dans la barre latérale et sélectionnez Générer des documents, ou utilisez le raccourci Ctrl + ..
Mintlify écrit automatiquement la documentation.

Exemple de code :

test("@e2e wait for api response", async ({ page }) => {
  const sidemenuPage = new SideMenuPage(page);
  await sidemenuPage.interceptApiLink.click();
  const response = await page.waitForResponse((response) =>
    response.url().includes("/comments")
  );
  expect(response.status()).toBe(200);
  await page.getByText("CREATE post").isVisible();
});

Documentation générée :

Le bloc de code est un cas de test qui vérifie si la réponse de l’API est reçue avec succès.

J’ai documenté un script de test, et Mintlify a réussi la description, sans effort !

Explorer les fonctionnalités de Mintlify

Mintlify regorge d’outils pour faire briller vos documents. Voici comment passer au niveau supérieur :

Éditeur Web : Modifiez les documents dans le navigateur via Tableau de bord > Éditeur. Tapez / pour les composants tels que les onglets ou les légendes.
Thèmes et style : Personnalisez les couleurs, les polices ou les logos dans docs.json. Essayez des thèmes comme prism ou default.
Intégration GitHub : Installez l’application GitHub Mintlify pour déployer automatiquement les modifications. Vérifiez le tableau de bord pour la configuration.
Analytique : Suivez l’engagement des utilisateurs dans Tableau de bord > Analytique pour voir les pages populaires ou les abandons.
Composants : Ajoutez des accordéons, des groupes de code ou des diagrammes Mermaid via MDX. Consultez https://mintlify.com/docs pour des exemples.

J’ai ajusté mon thème et ajouté des onglets, ce qui a donné à mes documents l’apparence d’une conception professionnelle en moins d’une heure !

Pour conclure : votre voyage Mintlify commence

Excellent travail, vous avez déverrouillé la puissance de Mintlify pour créer une documentation époustouflante et prête pour l’IA ! De l’installation de la CLI à la configuration de domaines personnalisés, de l’ingestion de l’IA, des serveurs MCP, des traductions et des aires de jeux OpenAPI, vous êtes prêt à créer des documents qui impressionneront les utilisateurs. Expérimentez avec de nouveaux composants, ajoutez plus de langues ou documentez vos API avec APIdog ! Bonne documentation !

button