En-tête de fichier
Configurez les titres de page, descriptions, icônes, remplacements de barre latérale et métadonnées SEO avec le bloc YAML frontmatter en haut de chaque fichier MDX.
Chaque fichier MDX commence par un bloc YAML entre des marqueurs ---. Ces métadonnées contrôlent le titre de votre page, l'apparence dans la barre latérale, et la façon dont la page s'affiche lors d'un partage sur les réseaux sociaux ou dans les résultats de recherche.
Frontmatter de base
Chaque page nécessite au moins un titre :
---
title: Getting Started
description: Learn the basics in 5 minutes
---Champs disponibles
Requis
| Champ | Type | Description |
|---|---|---|
title | string | Titre de la page affiché dans la navigation et l'onglet du navigateur |
Recommandé
| Champ | Type | Description |
|---|---|---|
description | string | Bref résumé pour le SEO et les résultats de recherche (50-160 caractères) |
Optionnel
| Champ | Type | Par 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 navigation dans la barre latérale |
mode | string | - | Définir sur "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 voir cette page. Définir cette option sur une page 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 l'ensemble du site est protégé via auth.password.enabled). Prend le dessus sur private: true si les deux sont définis. |
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 apparaît 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 à pleine 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'atterrissage, 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. Mettez les mots-clés importants en premier.
# 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 liées :
| 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: title
Correction : Ajoutez le champ title à votre frontmatter.
Error: Invalid frontmatter in "guide.mdx": unexpected token
Correction : Vérifiez :
- Les guillemets manquants autour des chaînes avec des caractères spéciaux
- L'indentation incorrecte
- Les deux-points manquants après les clés