6. Les erreurs les plus fréquentes des débutants

Erreurs fréquentes des débutants

Les pièges courants et comment les éviter

1. Penser que Mintlify héberge le site

Beaucoup de débutants croient que Mintlify publie directement leur site.

En réalité, Mintlify génère le code, mais c’est GitHub qui stocke et Vercel qui héberge.

Si vous modifiez une page sans publier vers GitHub, votre site ne changera pas.

2. Oublier de cliquer sur “Publish to GitHub”

C’est l’erreur la plus courante.

Vous modifiez une page, vous voyez l’aperçu, mais vous oubliez de publier.

Résultat : rien ne change en ligne.

Toujours cliquer sur Publish to GitHub après une modification.

3. Modifier la mauvaise page

Il arrive souvent de modifier une page qui porte un nom proche d’une autre.

Pour éviter ça :

• vérifiez le chemin du fichier
• vérifiez le titre dans l’éditeur
• vérifiez la sidebar

Une bonne organisation évite beaucoup d’erreurs.

4. Utiliser des séparateurs HTML non compatibles

Des éléments comme <hr /> peuvent provoquer des erreurs dans Mintlify.

Il vaut mieux utiliser des titres, des espaces ou des sections simples pour structurer vos pages.

5. Copier-coller du code avec des caractères spéciaux

Certains caractères (guillemets typographiques, flèches, symboles) peuvent casser la mise en forme.

Si vous copiez du texte depuis un autre site, vérifiez qu’il n’y a pas de caractères invisibles.

6. Ne pas comprendre le rôle de GitHub

GitHub n’est pas un éditeur : c’est un stockage et un déclencheur.

Si GitHub ne reçoit pas vos fichiers, Vercel ne peut pas mettre à jour votre site.

Comprendre ce rôle évite beaucoup de confusion.

7. Penser que Vercel met à jour instantanément

Vercel reconstruit votre site en quelques secondes, mais pas instantanément.

Il faut parfois attendre un court moment avant de voir les changements.

Un rafraîchissement forcé peut être nécessaire.

8. Oublier de vérifier la sidebar

Vous créez une nouvelle page, mais elle n’apparaît pas dans le menu.

C’est normal : il faut l’ajouter dans la sidebar.

Une page non référencée reste accessible, mais invisible dans la navigation.

9. Trop complexifier les pages

Les débutants ajoutent parfois trop de sections, trop de niveaux ou trop de contenu dans une seule page.

Il vaut mieux :

• faire des pages courtes
• séparer les sujets
• garder une structure simple

Une documentation claire est plus agréable à lire.

10. Ne pas tester après publication

Après chaque mise à jour :

• ouvrez votre site
• vérifiez la page modifiée
• assurez-vous que tout s’affiche correctement

Tester régulièrement évite les mauvaises surprises.

Résumé

Les erreurs les plus courantes viennent d’une mauvaise compréhension du workflow Mintlify → GitHub → Vercel, d’oublis de publication ou d’une structure trop complexe.

En appliquant quelques bonnes pratiques simples, vous évitez 90 % des problèmes.

Pour aller plus loin

• Documentation Mintlify : https://mintlify.com/docs
• Bonnes pratiques GitHub : https://docs.github.com
• Déploiement Vercel : https://vercel.com/docs