@astrojs/ markdoc

v0.11.0 GitHub npm Changelog

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 ?

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

Astro 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.

npx astro add markdoc

pnpm astro add markdoc

yarn astro add markdoc

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

Tout d’abord, installez le paquet @astrojs/markdoc :

npm install @astrojs/markdoc

pnpm add @astrojs/markdoc

yarn add @astrojs/markdoc

Ensuite, appliquez l’intégration à votre fichier astro.config.* en utilisant la propriété integrations :

import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
export default defineConfig({
  // ...
  integrations: [markdoc()],
});

Intégration dans un éditeur VS Code

Si 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 :

[
  {
    "id": "my-site",
    "path": "src/content",
    "schema": {
      "path": "markdoc.config.mjs",
      "type": "esm",
      "property": "default",
      "watch": true
    }
  }
]

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

Les 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 :

---
import { getEntryBySlug } from 'astro:content';

const entry = await getEntryBySlug('docs', 'why-markdoc');
const { Content } = await entry.render();
---

<!--Accéder aux propriétés du Frontmatter avec `data`-->
<h1>{entry.data.title}</h1>
<!--Rendre le contenu d'un Markdoc avec le composant Content-->
<Content />

Voir les docs de la collection de contenus Astro pour plus d’informations.

Passer les variables Markdoc

Vous 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 :

---
import { getEntryBySlug } from 'astro:content';

const entry = await getEntryBySlug('docs', 'why-markdoc');
const { Content } = await entry.render();
---

<!--Passer le paramètre `abTest` comme variable-->
<Content abTestGroup={Astro.params.abTestGroup} />

Maintenant, abTestGroup est disponible comme variable dans docs/why-markdoc.mdoc :

{% if $abTestGroup === 'image-optimization-lover' %}

Laissez-moi vous parler de l'optimisation des images...

{% /if %}

Pour rendre une variable globale à tous les fichiers Markdoc, vous pouvez utiliser l’attribut variables de votre markdoc.config.mjs|ts :

import { defineMarkdocConfig } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  variables: {
    environment: process.env.IS_PROD ? 'prod' : 'dev',
  },
});

Accéder au frontmatter à partir du contenu de votre Markdoc

Pour accéder à frontmatter, vous pouvez passer la propriété data de l’entrée comme une variable où vous affichez votre contenu :

---
import { getEntry } from 'astro:content';

const entry = await getEntry('docs', 'why-markdoc');
const { Content } = await entry.render();
---

<Content frontmatter={entry.data} />

Il est désormais accessible sous le nom de $frontmatter dans votre Markdoc.

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

Vous 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 :

import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  tags: {
    aside: {
      render: component('./src/components/Aside.astro'),
      attributes: {
        // Markdoc exige des définitions de type pour chaque attribut.
        // Ceux-ci doivent refléter le type `Props` du composant
        // que vous rendez.
        // Voir la documentation de Markdoc sur la définition des attributs.
        // https://markdoc.dev/docs/attributes#defining-attributes
        type: { type: String },
      },
    },
  },
});

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 :

# Bienvenue sur Markdoc 👋

{% aside type="tip" %}

Utilisez des balises comme cette fantaisie "aside" pour ajouter un peu de _flair_ à vos documents.

{% /aside %}

Utiliser des composants d’UI côté client

Les 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 :

---
import Aside from './Aside';
---

<Aside {...Astro.props} client:load />

Ce composant Astro peut maintenant être passé au props render pour n’importe quel tag ou node dans votre configuration :

import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  tags: {
    aside: {
      render: component('./src/components/ClientAside.astro'),
      attributes: {
        type: { type: String },
      },
    },
  },
});

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() :

import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  tags: {
    tabs: {
      render: component('@astrojs/starlight/components', 'Tabs'),
    },
  },
});

Cela génère la déclaration d’importation suivante en interne :

import { Tabs } from '@astrojs/starlight/components';

Partiels de Markdoc

La 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.

Cet exemple montre une partie de Markdoc pour un pied de page à utiliser dans les entrées de la collection de blogs :

Liens sociaux :

- [Twitter / X](https://twitter.com/astrodotbuild)
- [Discord](https://astro.build/chat)
- [GitHub](https://github.com/withastro/astro)

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 :

# Mon article de blog

{% partial file="./_footer.mdoc" %}

Mise en valeur de la syntaxe (highlighting)

@astrojs/markdoc fournit les extensions Shiki et Prism pour mettre en évidence vos blocs de code.

Shiki

Appliquez l’extension shiki() à votre configuration Markdoc en utilisant la propriété extends. Vous pouvez optionnellement passer un objet de configuration shiki :

import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import shiki from '@astrojs/markdoc/shiki';

export default defineMarkdocConfig({
  extends: [
    shiki({
      // Choisissez parmi les thèmes intégrés de Shiki (ou ajoutez les vôtres)
      // Défaut : 'github-dark'
      // https://shiki.style/themes
      theme: 'dracula',
      // Activer l'habillage des mots pour éviter le défilement horizontal
      // Défaut : false
      wrap: true,
      // Passer des langues personnalisées
      // Note : Shiki a d'innombrables langages intégrés, y compris `.astro` !
      // https://shiki.style/languages
      langs: [],
    }),
  ],
});

Prism

Appliquez l’extension prism() à votre configuration Markdoc en utilisant la propriété extends.

import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import prism from '@astrojs/markdoc/prism';

export default defineMarkdocConfig({
  extends: [prism()],
});

Pour en savoir plus sur la configuration des feuilles de style Prism, voir notre guide sur la coloration syntaxique.

Nœuds / éléments Markdoc personnalisés

Il 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 :

import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  nodes: {
    blockquote: {
      ...nodes.blockquote, // Application des valeurs par défaut de Markdoc pour les autres options
      render: component('./src/components/Quote.astro'),
    },
  },
});

Voir la documentation sur les nœuds Markdoc pour en savoir plus sur tous les nœuds et attributs intégrés.

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 :

import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  nodes: {
    heading: {
      ...nodes.heading, // Conserve la génération des liens d'ancrage par défaut
      render: component('./src/components/Heading.astro'),
    },
  },
});

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 - 6
id : string Un id généré à partir du contenu textuel de la rubrique. Cela correspond au slug généré par la fonction content render().

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

Le 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

Pour 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és src et alt de votre image au composant <Image /> :

---
import { Image } from "astro:assets";
interface Props {
  src: ImageMetadata;
  alt: string;
}
const { src, alt } = Astro.props;
---
<Image src={src} alt={alt} />

Le composant <Image /> requiert width et height 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 distante src est trouvée :
src/components/MarkdocImage.astro
```
---
import { Image } from "astro:assets";
interface Props {
  src: ImageMetadata | string;
  alt: string;
}
const { src, alt } = Astro.props;
---
<Image src={src} alt={alt} />
{
  typeof src === 'string' ? <img src={src} alt={alt} /> : <Image src={src} alt={alt} />
}
```

Configurez Markdoc pour remplacer le nœud d’image par défaut et afficher MarkdocImage.astro :

import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  nodes: {
    image: {
      ...nodes.image, // Appliquer les valeurs par défaut de Markdoc pour les autres options
      render: component('./src/components/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.
src/content/blog/post.mdoc
```

![Une photo de chat](/chat.jpg)


![Une photo de chien](https://example.com/chien.jpg)
```

Créer une balise d’image Markdoc personnalisée

Une 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 :

---
// src/components/MarkdocFigure.astro
import { Image } from "astro:assets";

interface Props {
  src: ImageMetadata | string;
  alt: string;
  width: number;
  height: number;
  caption: string;
}

const { src, alt, width, height, caption } = Astro.props;
---
<figure>
    <Image {src} {alt} {width} {height}  />
    {caption && <figcaption>{caption}</figcaption>}
</figure>

Configurez votre balise d’image personnalisée pour afficher votre composant Astro :

import { component, defineMarkdocConfig, nodes } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  tags: {
    image: {
      attributes: nodes.image.attributes,
      render: component('./src/components/MarkdocFigure.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 :
```
{% image src="./astro-logo.png" alt="Astro Logo" width="100" height="100" caption="une légende !" %}
```

Configuration de Markdoc

Le 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 :

import { defineMarkdocConfig } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  functions: {
    getCountryEmoji: {
      transform(parameters) {
        const [country] = Object.values(parameters);
        const countryToEmojiMap = {
          japan: '🇯🇵',
          spain: '🇪🇸',
          france: '🇫🇷',
        };
        return countryToEmojiMap[country] ?? '🏳';
      },
    },
  },
});

Vous pouvez désormais appeler cette fonction à partir de n’importe quelle entrée de contenu Markdoc :

¡Hola {% getCountryEmoji("spain") %}!

Voir la documentation Markdoc pour plus d’informations sur l’utilisation de variables ou de fonctions dans votre contenu.

Définir l’élément HTML racine

Markdoc 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 :

import { defineMarkdocConfig, nodes } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  nodes: {
    document: {
      ...nodes.document, // Application des valeurs par défaut pour les autres options
      render: null, // défaut : 'article'
    },
  },
});

Options de configuration de l’intégration

L’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`

Permet 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.

  import { defineConfig } from 'astro/config';
  import markdoc from '@astrojs/markdoc';

  export default defineConfig({
    // ...
    integrations: [markdoc({ allowHTML: true })],
  });

`ignoreIndentation`

Par 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.

  import { defineConfig } from 'astro/config';
  import markdoc from '@astrojs/markdoc';

  export default defineConfig({
    // ...
    integrations: [markdoc({ ignoreIndentation: true })],
  });

# Bienvenue à Markdoc avec des balises indentées 👋

# Note : Vous pouvez utiliser des espaces ou des tabulations pour l'indentation.

{% custom-tag %}
{% custom-tag %} ### Les balises peuvent être indentées pour une meilleure lisibilité

    {% another-custom-tag %}
      Il est plus facile à suivre lorsqu'il y a beaucoup d'imbrications.
    {% /another-custom-tag %}

{% /custom-tag %}
{% /custom-tag %}

Exemples

Le modèle de départ Astro Markdoc montre comment utiliser les fichiers Markdoc dans votre projet Astro.