@astrojs/ markdoc
Cette intégration Astro permet d’utiliser Markdoc pour créer des composants, des pages et des entrées de collection de contenu.
Pourquoi Markdoc ?
Titre de la section Pourquoi Markdoc ?Markdoc vous permet d’améliorer votre Markdown avec des composants Astro. Si vous avez du contenu existant rédigé dans Markdoc, cette intégration vous permet d’apporter ces fichiers à votre projet Astro en utilisant des collections de contenu.
Installation
Titre de la section InstallationAstro inclut une commande astro add
pour automatiser l’installation des intégrations officielles. Si vous préférez, vous pouvez installer les intégrations manuellement à la place.
Exécutez l’une des commandes suivantes dans une nouvelle fenêtre de terminal.
Si vous rencontrez des problèmes, n’hésitez pas à nous les signaler sur GitHub et essayez les étapes d’installation manuelle ci-dessous.
Installation manuelle
Titre de la section Installation manuelleTout d’abord, installez le paquet @astrojs/markdoc
:
Ensuite, appliquez l’intégration à votre fichier astro.config.*
en utilisant la propriété integrations
:
Intégration dans un éditeur VS Code
Titre de la section Intégration dans un éditeur VS CodeSi vous utilisez VS Code, il existe une extension de langage Markdoc officielle qui inclut la coloration syntaxique et l’autocomplétion pour les balises configurées. Voir le serveur de langue sur GitHub pour plus d’informations.
Pour configurer l’extension, créez un fichier markdoc.config.json
à la racine du projet avec le contenu suivant :
Définissez markdoc.config.mjs
comme fichier de configuration avec l’objet schema
, et définissez où vos fichiers Markdoc sont stockés en utilisant la propriété path
. Comme Markdoc est spécifique aux collections de contenu, vous pouvez utiliser src/content
.
Utilisation
Titre de la section UtilisationLes fichiers Markdoc ne peuvent être utilisés que dans les collections de contenus. Ajoutez des entrées à n’importe quelle collection de contenus en utilisant l’extension .mdoc
:
Répertoiresrc/
- …
Répertoirecontent/
- …
Répertoiredocs/
- …
- why-markdoc.mdoc
- quick-start.mdoc
Interrogez ensuite votre collection à l’aide des API de Collections de contenus :
Passer les variables Markdoc
Titre de la section Passer les variables MarkdocVous pouvez avoir besoin de passer les variables à votre contenu. C’est utile pour passer des paramètres SSR comme les tests A/B.
Les variables peuvent être transmises en tant que props via le composant Content
:
Maintenant, abTestGroup
est disponible comme variable dans docs/why-markdoc.mdoc
:
Pour rendre une variable globale à tous les fichiers Markdoc, vous pouvez utiliser l’attribut variables
de votre markdoc.config.mjs|ts
:
Accéder au frontmatter à partir du contenu de votre Markdoc
Titre de la section Accéder au frontmatter à partir du contenu de votre MarkdocPour accéder à frontmatter, vous pouvez passer la propriété data
de l’entrée comme une variable où vous affichez votre contenu :
Il est désormais accessible sous le nom de $frontmatter
dans votre Markdoc.
Afficher les composants
Titre de la section Afficher les composants@astrojs/markdoc
offre des options de configuration pour utiliser toutes les fonctionnalités de Markdoc et connecter des composants d’interface utilisateur à votre contenu.
Utiliser les composants Astro comme balises Markdoc
Titre de la section Utiliser les composants Astro comme balises MarkdocVous pouvez configurer des Markdoc tags qui correspondent à des composants .astro
. Vous pouvez ajouter une nouvelle balise en créant un fichier markdoc.config.mjs|ts
à la racine de votre projet et en configurant l’attribut tag
.
Cet exemple rend un composant Aside
, et permet de passer une propriété type
sous forme de chaîne de caractères :
Ce composant peut maintenant être utilisé dans vos fichiers Markdoc avec la balise {% aside %}
. Les enfants seront transmis au slot par défaut de votre composant :
Utiliser des composants d’UI côté client
Titre de la section Utiliser des composants d’UI côté clientLes balises et les nœuds sont limités aux fichiers .astro
. Pour intégrer des composants d’interface utilisateur côté client dans Markdoc, utilisez un composant .astro
enveloppant qui affiche un composant de framework avec la directive client:
de votre choix.
Cet exemple enveloppe un composant React Aside.tsx
avec un composant ClientAside.astro
:
Ce composant Astro peut maintenant être passé au props render
pour n’importe quel tag ou node dans votre configuration :
Utiliser des composants Astro à partir de paquets npm et de fichiers TypeScript.
Titre de la section Utiliser des composants Astro à partir de paquets npm et de fichiers TypeScript.Vous pouvez avoir besoin d’utiliser des composants Astro exposés en tant qu’exportations nommées à partir de fichiers TypeScript ou JavaScript. Cela est fréquent lors de l’utilisation de paquets npm et de systèmes de conception.
Vous pouvez passer le nom de l’importation comme second argument à la fonction component()
:
Cela génère la déclaration d’importation suivante en interne :
Partiels de Markdoc
Titre de la section Partiels de MarkdocLa balise {% partial %}
vous permet d’afficher d’autres fichiers .mdoc
dans votre contenu Markdoc.
Cette fonction est utile pour réutiliser le contenu de plusieurs documents et permet d’avoir des fichiers de contenu .mdoc
qui ne suivent pas le schéma de votre collection.
Utilisez un préfixe _
souligné pour les fichiers ou répertoires partiels. Cela permet d’exclure les fichiers partiels des requêtes de collecte de contenu.
Cet exemple montre une partie de Markdoc pour un pied de page à utiliser dans les entrées de la collection de blogs :
Utilisez la balise {% partial %}
avec pour afficher le pied de page au bas de l’article d’un blog. Appliquez l’attribut file
avec le chemin du fichier, en utilisant soit un chemin relatif, soit un alias d’importation :
Mise en valeur de la syntaxe (highlighting)
Titre de la section Mise en valeur de la syntaxe (highlighting)@astrojs/markdoc
fournit les extensions Shiki et Prism pour mettre en évidence vos blocs de code.
Appliquez l’extension shiki()
à votre configuration Markdoc en utilisant la propriété extends
. Vous pouvez optionnellement passer un objet de configuration shiki :
Appliquez l’extension prism()
à votre configuration Markdoc en utilisant la propriété extends
.
Nœuds / éléments Markdoc personnalisés
Titre de la section Nœuds / éléments Markdoc personnalisésIl se peut que vous souhaitiez afficher les éléments Markdown standard, tels que les paragraphes et le texte en gras, en tant que composants Astro. Pour cela, vous pouvez configurer un nœud Markdoc. Si un nœud donné reçoit des attributs, ceux-ci seront disponibles en tant que props du composant.
Cet exemple affiche les blockquotes avec un composant personnalisé Quote.astro
:
En-têtes personnalisés
Titre de la section En-têtes personnalisés@astrojs/markdoc
ajoute automatiquement des liens d’ancrage à vos titres, et génère une liste de titres
via l’API des Collections de contenu. Pour personnaliser davantage le rendu des titres, vous pouvez appliquer un composant Astro en tant que nœud Markdoc.
Cet exemple rend un composant Heading.astro
en utilisant la propriété render
:
Tous les titres Markdown rendront le composant Heading.astro
et passeront les attributs
suivants en tant qu’accessoires du composant :
level : number
Le niveau de la rubrique 1 - 6id : string
Unid
généré à partir du contenu textuel de la rubrique. Cela correspond auslug
généré par la fonction contentrender()
.
Par exemple, le titre ### Level 3 heading!
passera level : 3
et id : 'level-3-heading'
en tant qu’éléments du composant.
Composants d’image personnalisés
Titre de la section Composants d’image personnalisésLe composant Astro <Image />
ne peut pas être utilisé directement dans Markdoc. Cependant, vous pouvez configurer un composant Astro pour remplacer le nœud d’image par défaut chaque fois que la syntaxe d’image native ![]()
est utilisée, ou en tant que balise Markdoc personnalisée pour vous permettre de spécifier des attributs d’image supplémentaires.
Remplacer le nœud d’image par défaut de Markdoc
Titre de la section Remplacer le nœud d’image par défaut de MarkdocPour remplacer le nœud d’image par défaut, vous pouvez configurer un composant .astro
qui sera affiché à la place d’un <img>
standard.
-
Créez un composant
MarkdocImage.astro
personnalisé pour passer les propriétéssrc
etalt
de votre image au composant<Image />
: -
Le composant
<Image />
requiertwidth
etheight
pour les images à distance qui ne peuvent pas être fournies à l’aide de la syntaxe![]()
. Pour éviter les erreurs lors de l’utilisation d’images distantes, mettez à jour votre composant pour afficher une balise HTML standard<img>
lorsqu’une URL distantesrc
est trouvée : -
Configurez Markdoc pour remplacer le nœud d’image par défaut et afficher
MarkdocImage.astro
: -
La syntaxe de l’image native dans n’importe quel fichier
.mdoc
utilisera désormais le composant<Image />
pour optimiser vos images locales. Les images distantes peuvent toujours être utilisées, mais ne seront pas affichées par le composant<Image />
d’Astro.
Créer une balise d’image Markdoc personnalisée
Titre de la section Créer une balise d’image Markdoc personnaliséeUne balise Markdoc image
vous permet de définir des attributs supplémentaires sur votre image qui ne sont pas possibles avec la syntaxe ![]()
. Par exemple, les balises d’images personnalisées vous permettent d’utiliser le composant <Image />
d’Astro pour les images distantes qui nécessitent une largeur
et une hauteur
.
Les étapes suivantes permettent de créer une balise image Markdoc personnalisée pour afficher un élément <figure>
avec une légende, en utilisant le composant Astro <Image />
pour optimiser l’image.
-
Créez un composant
MarkdocFigure.astro
pour recevoir les props nécessaires et afficher une image avec une légende : -
Configurez votre balise d’image personnalisée pour afficher votre composant Astro :
-
Utilisez la balise
image
dans les fichiers Markdoc pour afficher une figure avec légende, en fournissant tous les attributs nécessaires à votre composant :
Configuration de Markdoc
Titre de la section Configuration de MarkdocLe fichier markdoc.config.mjs|ts
accepte toutes les options de configuration de Markdoc, y compris les tags et les fonctions.
Vous pouvez passer ces options à partir de l’exportation par défaut dans votre fichier markdoc.config.mjs|ts
:
Vous pouvez désormais appeler cette fonction à partir de n’importe quelle entrée de contenu Markdoc :
Définir l’élément HTML racine
Titre de la section Définir l’élément HTML racineMarkdoc entoure les documents d’une balise <article>
par défaut. Ce comportement peut être modifié à partir du noeud Markdoc document
. Il accepte un nom d’élément HTML ou null
si vous préférez supprimer l’élément enveloppant :
Options de configuration de l’intégration
Titre de la section Options de configuration de l’intégrationL’intégration Astro Markdoc gère la configuration des options et des capacités de Markdoc qui ne sont pas disponibles dans le fichier markdoc.config.js
.
allowHTML
Titre de la section allowHTMLPermet d’écrire des balises HTML à côté des balises et des nœuds Markdoc.
Par défaut, Markdoc ne reconnaît pas les balises HTML comme du contenu sémantique.
Pour obtenir une expérience plus proche de Markdoc, où les éléments HTML peuvent être inclus avec votre contenu, mettez allowHTML:true
comme option d’intégration markdoc
. Cela activera l’analyse HTML dans les balises Markdoc.
Lorsque l’option allowHTML
est activée, le balisage HTML à l’intérieur des documents Markdoc sera rendu comme des éléments HTML réels (y compris <script>
), ce qui rend possible des vecteurs d’attaque comme XSS. Veillez à ce que les balises HTML proviennent de sources fiables.
ignoreIndentation
Titre de la section ignoreIndentationPar défaut, tout contenu indenté de quatre espaces est traité comme un bloc de code. Malheureusement, ce comportement rend difficile l’utilisation de niveaux d’indentation arbitraires pour améliorer la lisibilité des documents à la structure complexe.
Lors de l’utilisation de balises imbriquées dans Markdoc, il peut être utile d’indenter le contenu à l’intérieur des balises afin que le niveau de profondeur soit clair. Pour prendre en charge l’indentation arbitraire, nous devons désactiver les blocs de code basés sur l’indentation et modifier plusieurs autres règles d’analyse markdown-it qui prennent en compte les blocs de code basés sur l’indentation. Ces modifications peuvent être appliquées en activant l’option ignoreIndentation.
Exemples
Titre de la section Exemples- Le modèle de départ Astro Markdoc montre comment utiliser les fichiers Markdoc dans votre projet Astro.