Coloration syntaxique

Astro est doté d’un support intégré pour Shiki et Prism. Il fournit une coloration syntaxique pour :

toutes les barrières de code (```) utilisées 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 guillemets d’ouverture pour indiquer comment colorer et styliser 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 stylisés par Shiki par défaut, préconfigurés avec le thème github-dark. La sortie compilée sera limitée aux styles en ligne 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.

Les blocs de code Astro sont stylisés à l’aide de la classe .astro-code, vous devrez donc remplacer la classe .shiki dans les exemples par .astro-code.

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 en ligne. -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  sera rendu en ligne.
</p>
<!-- Facultatif : defaultColor -->
<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

Transformateurs

Ajouté à la version : astro@4.11.0

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 styliser les classes.

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

npm install @astrojs/prism

pnpm add @astrojs/prism

yarn add @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.

Choisissez une feuille de style prédéfinie parmi les Thèmes Prism disponibles.
Ajoutez cette feuille de style au répertoire public/ de votre projet.
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.

Contribuer

Communauté