import Since from '/components/Since.astro'; import ReadMore from '/components/ReadMore.astro'; import { Steps } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

Astro est doté d'une prise en charge intégrée pour Shiki et Prism. Il fournit une coloration syntaxique pour :

• tous les délimiteurs de code (```) utilisés dans un fichier Markdown ou MDX.
• les contenus dans le composant intégré <Code /> (alimenté par Shiki) dans les fichiers .astro.
• les contenus dans le composant <Prism /> (alimenté par Prism) dans les fichiers .astro.

Ajoutez des intégrations communautaires telles que Expressive Code pour encore plus d’options de marquage et d’annotation de texte dans vos blocs de code.

Blocs de code Markdown

Un bloc de code Markdown est indiqué par un bloc avec trois accents graves ``` au début et à la fin. Vous pouvez indiquer le langage de programmation utilisé après les accents graves d'ouverture pour indiquer comment colorer et mettre en forme votre code pour le rendre plus facile à lire.

```js// Code Javascript avec coloration syntaxique.var fun = function lang(l) {  dateformat.i18n = require('./lang/' + l);  return true;};```

Les blocs de code Markdown d'Astro sont mis en forme par Shiki par défaut, préconfigurés avec le thème github-dark. La sortie compilée sera limitée aux styles incorporés sans classes CSS, feuilles de style ou JS côté client superflus.

Vous pouvez ajouter une feuille de style Prism et passer à la mise en évidence de Prism, ou désactivez complètement la coloration syntaxique d'Astro, avec l'option de configuration markdown.syntaxHighlight.

Consultez la référence markdown.shikiConfig complète pour avoir un aperçu complet des options de coloration syntaxique Markdown disponibles lors de l'utilisation de Shiki.

Définir un thème Shiki par défaut

Vous pouvez configurer n'importe quel thème Shiki intégré pour vos blocs de code Markdown dans votre configuration Astro :

import { defineConfig } from 'astro/config';export default defineConfig({  markdown: {    shikiConfig: {      theme: 'dracula',    },  },});

Consultez la référence de configuration complète de Shiki pour avoir un aperçu complet des options de bloc de code Markdown.

Définition des thèmes pour les modes clair et sombre

Vous pouvez spécifier deux thèmes Shiki pour les modes clair et sombre dans votre configuration Astro :

import { defineConfig } from 'astro/config';export default defineConfig({  markdown: {    shikiConfig: {      themes: {        light: 'github-light',        dark: 'github-dark',      },    },  },});

Ensuite, ajoutez les variables CSS du mode sombre de Shiki via une requête média ou des classes à appliquer à tous vos blocs de code Markdown par défaut. Remplacez la classe .shiki dans les exemples de la documentation de Shiki par .astro-code :

@media (prefers-color-scheme: dark) {  .shiki,  .shiki span {  .astro-code,  .astro-code span {    color: var(--shiki-dark) !important;    background-color: var(--shiki-dark-bg) !important;    /* Facultatif, si vous souhaitez également des styles de police */    font-style: var(--shiki-dark-font-style) !important;    font-weight: var(--shiki-dark-font-weight) !important;    text-decoration: var(--shiki-dark-text-decoration) !important;  }}

Consultez la référence de configuration complète de Shiki pour avoir un aperçu complet des options de bloc de code Markdown.

Ajouter votre propre thème Shiki

Au lieu d’utiliser l’un des thèmes prédéfinis de Shiki, vous pouvez importer un thème Shiki personnalisé à partir d’un fichier local.

import { defineConfig } from 'astro/config';import customTheme from './my-shiki-theme.json';export default defineConfig({  markdown: {    shikiConfig: {       theme: customTheme,    },  },});

Personnaliser les thèmes Shiki

Vous pouvez suivre la propre documentation des thèmes de Shiki pour plus d'options de personnalisation des thèmes, les bascules entre les modes clair et sombre ou l'application de styles via des variables CSS.

Vous devrez ajuster les exemples de la documentation de Shiki pour votre projet Astro en effectuant les substitutions suivantes :

• Les blocs de code sont mis en forme à l'aide de la classe .astro-code au lieu de .shiki
• Lors de l'utilisation du thème css-variables, les propriétés personnalisées sont préfixées par --astro-code- au lieu de --shiki-

Composants pour les blocs de code

Il existe deux composants Astro disponibles pour les fichiers .astro et .mdx pour restituer les blocs de code : <Code /> et <Prism />.

Vous pouvez référencer les Props de ces composants à l'aide de l'utilitaire de type ComponentProps.

<Code />

Ce composant est alimenté en interne par Shiki. Il prend en charge tous les thèmes et langages Shiki populaires ainsi que plusieurs autres options Shiki telles que les thèmes personnalisés, les langages, les transformateurs et les couleurs par défaut.

Ces valeurs sont transmises au composant <Code /> en utilisant respectivement les attributs theme, lang, transformers et defaultColor comme props. Le composant <Code /> n'héritera pas de vos paramètres shikiConfig pour les blocs de code Markdown.

---import { Code } from 'astro:components';---<!-- La syntaxe met en évidence du code JavaScript. --><Code code={`const foo = 'bar';`} lang="js" /><!-- Facultatif : Personnaliser votre thème. --><Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" /><!-- Facultatif : Activer le retour à la ligne. --><Code code={`const foo = 'bar';`} lang="js" wrap /><!-- Facultatif : Générer du code au sein du texte. --><p>  <Code code={`const foo = 'bar';`} lang="js" inline />  sera rendu au sein du texte.</p><!-- Facultatif : defaultColor --><Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

Transformateurs

Les transformateurs de Shiki peuvent éventuellement être appliqués au code en les transmettant via la propriété transformers sous forme de tableau. Depuis Astro v4.14.0, vous pouvez également fournir une chaîne de caractères à l'attribut meta de Shiki pour transmettre des options aux transformateurs.

Notez que transformers n'applique que les classes et vous devez fournir vos propres règles CSS pour cibler les éléments de votre bloc de code.

---import { transformerNotationFocus, transformerMetaHighlight } from '@shikijs/transformers'import { Code } from 'astro:components'const code = `const foo = 'hello'const bar = ' world'console.log(foo + bar) // [!code focus]`---<Code  code={code}  lang="js"  transformers={[transformerMetaHighlight()]}  meta="{1,3}"/>  <style is:global>  pre.has-focused .line:not(.focused) {    filter: blur(1px);  }</style>

<Prism />

Ce composant fournit une coloration syntaxique spécifique au langage pour les blocs de code en appliquant les classes CSS de Prism. Notez que vous devez fournir une feuille de style CSS de Prism (ou apporter la vôtre) pour ajouter des styles aux classes.

Pour utiliser le composant de coloration syntaxique Prism, vous devez installer le paquet @astrojs/prism :

Ensuite, vous pouvez importer et utiliser le composant <Prism /> comme n'importe quel autre composant Astro, en passant un langage et le code à restituer.

---import { Prism } from '@astrojs/prism';---<Prism lang="js" code={`const foo = 'bar';`} />

En plus de la liste des langages pris en charge par Prism, vous pouvez également utiliser lang="astro" pour afficher les blocs de code Astro.

Ajouter une feuille de style Prism

Si vous choisissez d'utiliser Prism (soit en configurant markdown.syntaxHighlight: 'prism' ou avec le composant <Prism />), Astro appliquera les classes CSS de Prism à votre code au lieu de celles de Shiki. Vous devrez apporter votre propre feuille de style CSS pour que la coloration syntaxique apparaisse.

2. Ajoutez cette feuille de style au répertoire public/ de votre projet.

3. Chargez-la dans la balise <head> dans un composant de mise en page à l'aide d'une balise <link>. (Voir Utilisation de base de Prism.)

Vous pouvez également consulter la liste des langages pris en charge par Prism pour les options et leur utilisation.