Frontmatter
Configurez les titres, descriptions, icônes, remplacements de barre latérale et métadonnées SEO avec le bloc YAML frontmatter en tête de chaque fichier MDX.
Chaque fichier MDX commence par un bloc YAML entre des marqueurs ---. Ces métadonnées contrôlent le titre de la page, l'apparence dans la barre latérale, et la façon dont la page s'affiche lors des partages sur les réseaux sociaux ou dans les résultats de recherche.
Frontmatter de base
Chaque page nécessite au minimum un titre :
---
title: Getting Started
description: Learn the basics in 5 minutes
---Champs disponibles
Obligatoire
| Champ | Type | Description |
|---|---|---|
title | string | Titre de la page affiché dans la navigation et l'onglet du navigateur |
Recommandé
| Champ | Type | Description |
|---|---|---|
description | string | Résumé court pour le SEO et les résultats de recherche (50-160 caractères) |
Optionnel
| Champ | Type | Défaut | Description |
|---|---|---|---|
icon | string | - | Icône Font Awesome affichée à côté du titre de la page dans la barre latérale |
sidebarTitle | string | title | Titre plus court pour la barre latérale |
mode | string | - | Définir à "wide" pour une mise en page pleine largeur |
hideFooter | boolean | false | Masquer le pied de page social sur cette page |
rss | boolean | false | Activer la génération de flux RSS à partir des composants Update sur cette page |
private | boolean | false | Exiger le mot de passe du site pour consulter cette page. Activer ceci sur une page quelconque active le mode pages spécifiques lors du prochain build. |
public | boolean | false | Exempter cette page de la protection par mot de passe (utilisé lorsque tout le site est protégé via auth.password.enabled). Prend le dessus sur private: true si les deux sont définis. |
SEO & Social
Contrôlez l'apparence de la page dans les résultats de recherche et les aperçus sociaux. Définissez ces valeurs comme clés de premier niveau ou dans un bloc seo: imbriqué. Les deux fonctionnent, et les valeurs par page remplacent les valeurs par défaut seo.metatags de votre docs.json.
| Champ | Type | Défaut | Description |
|---|---|---|---|
keywords | string[] | - | Mots-clés de recherche, émis sous forme de balise <meta name="keywords"> |
canonical | string | auto | URL canonique de cette page, remplaçant celle générée automatiquement |
noindex | boolean | false | Exclure cette page des moteurs de recherche et du sitemap |
og:* / twitter:* | string | - | Balises Open Graph et Twitter/X pour les aperçus sociaux (ex. og:title, og:image, twitter:card) |
seo | object | - | Bloc imbriqué contenant l'un des éléments ci-dessus ainsi que des balises méta personnalisées |
---
title: API Reference
description: REST endpoints and authentication
"og:image": /images/api-card.png
"twitter:card": summary_large_image
canonical: https://docs.acme.com/api-reference
---Consultez Optimisation SEO pour la liste complète des balises prises en charge et des exemples.
Après un build, collez l'URL de la page dans l'outil gratuit OpenGraph Preview pour voir comment ces balises s'affichent sur X, Facebook, LinkedIn, Slack, Discord, et plus encore.
Exemples
Page de documentation standard
---
title: Authentication
description: Secure your API with OAuth 2.0 and API keys
icon: lock
---Titre long avec remplacement de barre latérale
---
title: Configuring Single Sign-On with SAML 2.0
sidebarTitle: SSO Setup
description: Set up enterprise SSO for your organization
---Le titre complet s'affiche sur la page, tandis que le sidebarTitle plus court maintient une navigation claire.
Mise en page large
---
title: API Reference
description: Complete API documentation
mode: wide
---Le mode large supprime la table des matières et étend le contenu sur toute la largeur. Utile pour les pages de référence API ou le contenu avec des tableaux larges.
Masquer le pied de page
---
title: Custom Landing
description: A focused landing page experience
hideFooter: true
---Utilisez hideFooter pour les pages d'accueil, les pages de changelog, ou toute page où vous souhaitez une section inférieure plus épurée sans liens sociaux.
Bonnes pratiques SEO
Votre titre apparaît dans :
- Les onglets du navigateur
- Les résultats des moteurs de recherche
- La barre latérale de navigation
- Les partages sur les réseaux sociaux
Gardez les titres sous 60 caractères. Placez les mots-clés importants en début.
# Good - clear and keyword-rich
title: Deploy to Production
# Avoid - vague or too long
title: How to Deploy Your Application to Production ServersLes descriptions apparaissent dans les résultats de recherche et les aperçus sociaux. Visez 50-160 caractères qui :
- Résument le contenu de la page
- Incluent des mots-clés pertinents
- Incitent les utilisateurs à cliquer
# Good - actionable and specific
description: Deploy your docs to production in under 2 minutes with zero configuration
# Avoid - generic or missing
description: Documentation pageLes icônes aident les utilisateurs à parcourir la navigation rapidement. Utilisez la même icône pour les pages connexes :
| Sujet | Icône suggérée |
|---|---|
| Démarrage | rocket |
| Authentification | lock |
| Référence API | code |
| Paramètres | gear |
| Facturation | credit-card |
Parcourez les icônes sur Font Awesome.
Validation
Jamdesk valide le frontmatter lors du build. Erreurs courantes :
Error: Page "api/auth.mdx" is missing required field: titleCorrection : Ajoutez le champ title à votre frontmatter.
Error: Invalid frontmatter in "guide.mdx": unexpected tokenCorrection : Vérifiez :
- Les guillemets manquants autour des chaînes contenant des caractères spéciaux
- Une indentation incorrecte
- Des deux-points manquants après les clés
Collez le bloc entre les marqueurs --- dans le YAML Validator gratuit pour identifier précisément la ligne et la colonne de l'erreur.