Aller au contenu principal
Version: 2.0.0-beta.3

Blocs de code

Les blocs de code dans la documentation sont super-puissants 💪.

Titre du code#

Vous pouvez ajouter un titre au bloc de code en ajoutant la clé title après le language (laisser un espace entre les deux).

```jsx title="/src/components/HelloCodeTitle.js"function HelloCodeTitle(props) {  return <h1>Hello, {props.name}</h1>;}```
/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {  return <h1>Hello, {props.name}</h1>;}

Coloration syntaxique#

Les blocs de code sont des blocs de texte enveloppés par des chaînes de 3 backticks. Vous pouvez consulter cette référence pour les spécifications du MDX.

```jsxconsole.log('Chaque dépôt doit être accompagné d'une mascotte.');```

Utilisez la méta-chaîne du langage correspondant pour votre bloc de code et Docusaurus récupérera automatiquement la coloration syntaxique, alimentée par Prism React Renderer.

console.log('Chaque dépôt doit être accompagné d'une mascotte.');

Thème#

Par défaut, le thème de coloration syntaxique de Prism que nous utilisons est Palenight. Vous pouvez changer cela pour un autre thème en passant le champ theme dans prism en tant que themeConfig dans votre docusaurus.config.js.

Par exemple, si vous préférez utiliser le thème de coloration dracula :

docusaurus.config.js
module.exports = {  themeConfig: {    prism: {      theme: require('prism-react-renderer/themes/dracula'),    },  },};

Langages prises en charge#

Par défaut, Docusaurus est fourni avec un sous-ensemble de langages couramment utilisés.

caution

Certains langages populaires comme Java, C# ou PHP ne sont pas activés par défaut.

Pour ajouter la coloration syntaxique pour n'importe lequel des autres langages pris en charge par Prism, définissez-la dans un tableau de langages supplémentaires.

Par exemple, si vous voulez ajouter une coloration pour le langage powershell :

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    prism: {      additionalLanguages: ['powershell'],    },    // ...  },};

Si vous souhaitez ajouter la coloration pour des langages qui ne sont pas encore pris en charge par Prism, vous pouvez « swizzler » le prism-include-languages :

npm run swizzle @docusaurus/theme-classic prism-include-languages

Il génèrera prism-include-languages.js dans votre dossier src/theme. Vous pouvez ajouter le support de mise en évidence pour les langages personnalisés en éditant prism-include-languages.js:

src/theme/prism-include-languages.js
const prismIncludeLanguages = (Prism) => {  // ...
  additionalLanguages.forEach((lang) => {    require(`prismjs/components/prism-${lang}`); // eslint-disable-line  });
  require('/path/to/your/prism-language-definition');
  // ...};

Vous pouvez vous référer aux définitions officielles des langages de Prism lorsque vous rédigez vos propres définitions de langage.

Surlignage de la ligne#

Vous pouvez mettre en évidence certaines lignes de code en spécifiant des plages de lignes après la méta-chaîne du langage (laissez un espace après le langage).

```jsx {3}function HighlightSomeText(highlight) {  if (highlight) {    return 'Ce texte est mis en évidence !';  }
  return 'Rien de mis en évidence';}```
function HighlightSomeText(highlight) {  if (highlight) {    return 'Ce texte est mis en évidence !';  }
  return 'Rien de mis en évidence';}

Pour cela, Docusaurus ajoute la classe docusaurus-highlight-code-line aux lignes surlignées. Vous devrez définir votre propre style pour ce CSS, peut-être dans votre src/css/custom.css avec une couleur d'arrière-plan personnalisée qui dépend de votre thème de coloration syntaxique sélectionné. La couleur indiquée ci-dessous fonctionne pour le thème de surbrillance par défaut (Palenight), donc si vous utilisez un autre thème, vous devrez modifier la couleur en conséquence.

/src/css/custom.css
.docusaurus-highlight-code-line {  background-color: rgb(72, 77, 91);  display: block;  margin: 0 calc(-1 * var(--ifm-pre-padding));  padding: 0 var(--ifm-pre-padding);}
/* Si vous avez un thème de coloration syntaxique différent pour le mode sombre. */html[data-theme='dark'] .docusaurus-highlight-code-line {  /* Couleur qui fonctionne avec le thème de la coloration syntaxique en mode sombre */  background-color: rgb(100, 100, 100);}

Surlignage sur plusieurs lignes#

Pour surligner plusieurs lignes, séparez les numéros de lignes par des virgules ou utilisez la syntaxe de l'intervalle pour sélectionner un morceau de lignes. Cette fonctionnalité utilise la bibliothèque parse-number-range et vous pouvez trouver plus de syntaxe dans les détails de leur projet.

```jsx {1,4-6,11}import React from 'react';
function MyComponent(props) {  if (props.isBar) {    return <div>Bar</div>;  }
  return <div>Foo</div>;}
export default MyComponent;```
import React from 'react';
function MyComponent(props) {  if (props.isBar) {    return <div>Bar</div>;  }
  return <div>Foo</div>;}
export default MyComponent;

Surlignage avec des commentaires#

Vous pouvez également utiliser des commentaires avec highlight-next-line, highlight-start, et highlight-end pour sélectionner quelles lignes sont surlignées.

```jsxfunction HighlightSomeText(highlight) {  if (highlight) {    // highlight-next-line    return 'Ce texte est surligné! ;  }
  retourne 'Rien de surligné' ;}
fonction HighlightMoreText(highlight) {  // surligne-start  if (highlight) {    return 'Cette plage est surlignée! ;  }  // highlight-end
  retourne 'Rien en surbrillance';

}

```
function HighlightSomeText(highlight) {  if (highlight) {    return 'Ce texte est surligné! ;  }
  retourne 'Rien de surligné' ;}
fonction HighlightMoreText(highlight) {  // surligne-start  if (highlight) {    return 'Cette plage est surlignée! ;  }
  return 'Rien en surbrillance' ;}

Syntaxe de commentaire supportée :

LangageSyntaxe
JavaScript/* ... */ et // ...
JSX{/* ... */}
Python# ...
HTML<!-- ... -->

S'il y a une syntaxe qui n'est pas actuellement supportée, nous sommes ouverts à les ajouter ! Les pull requests sont les bienvenues.

Éditeur de code interactif#

(Propulsé par React Live)

Vous pouvez créer un éditeur de code interactif avec le plugin @docusaurus/theme-live-codeblock.

Tout d'abord, ajoutez le plugin à votre package.

npm install --save @docusaurus/theme-live-codeblock

Vous devez également ajouter le plugin à votre docusaurus.config.js.

module.exports = {  // ...  themes: ['@docusaurus/theme-live-codeblock'],  // ...};

Pour utiliser le plugin, créez un bloc de code avec live attaché à la méta chaîne de langage.

```jsx livefunction Clock(props) {  const [date, setDate] = useState(new Date());  useEffect(() => {    var timerID = setInterval(() => tick(), 1000);
    return function cleanup() {      clearInterval(timerID);    };  });
  function tick() {    setDate(new Date());  }
  return (    <div>      <h2>Il est {date.toLocaleTimeString()}.</h2>    </div>  );}```

Le bloc de code sera rendu en tant qu'éditeur interactif. Les modifications apportées au code se répercuteront en temps réel sur le panneau des résultats.

Éditeur en ligne
Résultat
SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

Imports#

react-live et imports

Il n'est pas possible d'importer des composants directement depuis l'éditeur de code de react-live, vous devez définir les importations nécessaires au préalable.

Par défaut, toutes les importations de React sont disponibles. Si vous avez besoin d'un plus grand nombre d'importations à disposition, swizzlez la portée de react-live :

npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope
src/theme/ReactLiveScope/index.js
import React from 'react';
const ButtonExample = (props) => (  <button    {...props}    style={{      backgroundColor: 'white',      border: 'solid red',      borderRadius: 20,      padding: 10,      cursor: 'pointer',      ...props.style,    }}  />);
// Ajoutez les importations react-live dont vous avez besoin iciconst ReactLiveScope = {  React,  ...React,  ButtonExample,};
export default ReactLiveScope;

Le composant ButtonExample est maintenant disponible pour être utilisé :

Éditeur en ligne
Résultat
SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

Blocs de code multi-langages#

Avec MDX, vous pouvez facilement créer des composants interactifs dans votre documentation, par exemple, pour afficher du code dans plusieurs langages de programmation et basculer entre eux en utilisant un composant d'onglets.

Au lieu de mettre en place un composant dédié aux blocs de code pour la prise en charge de multi-langage, nous avons implémenté un composant Tabs générique dans le thème classic afin que vous puissiez l'utiliser également pour d'autres scénarios sans code.

L'exemple suivant montre comment vous pouvez avoir des onglets de code multi-language dans vos documents. Notez que les lignes vides au-dessus et au-dessous de chaque bloc de langage sont intentionnelles. Ceci est une limitation actuelle de MDX, vous devez laisser des lignes vides autour de la syntaxe Markdown pour que l'analyseur MDX sache que c'est la syntaxe Markdown et non JSX.

import Tabs from '@theme/Tabs';import TabItem from '@theme/TabItem';
<Tabs  defaultValue="js"  values={[    { label: 'JavaScript', value: 'js', },    { label: 'Python', value: 'py', },    { label: 'Java', value: 'java', },  ]}><TabItem value="js">
```jsfunction helloWorld() {  console.log('Hello, world!');}```
</TabItem><TabItem value="py">
```pydef hello_world():  print 'Hello, world!'```
</TabItem><TabItem value="java">
```javaclass HelloWorld {  public static void main(String args[]) {    System.out.println("Hello, World");  }}```
</TabItem></Tabs>

Et vous obtiendrez les éléments suivants :

function helloWorld() {  console.log('Hello, world!');}

Vous pouvez implémenter votre propre abstraction <MultiLanguageCode /> si vous trouvez l'approche ci-dessus trop verbeuse. Nous pourrions en implémenter un à l'avenir pour des raisons de commodité.

If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the Syncing tab choices section.