Aller au contenu principal
Version: 2.0.0-beta.10 🚧

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.

```jsx
console.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'],
},
// ...
},
};

Après avoir ajouté additionalLanguages, redémarrez Docusaurus.

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.

```jsx
function 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 live
function 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
Loading...

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 ici
const ReactLiveScope = {
React,
...React,
ButtonExample,
};

export default ReactLiveScope;

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

Éditeur en ligne
Résultat
Loading...

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>
<TabItem value="js" label="JavaScript">

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

</TabItem>
<TabItem value="py" label="Python">

```py
def hello_world():
print 'Hello, world!'
```

</TabItem>
<TabItem value="java" label="Java">

```java
class 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!');
}

Si vous avez plusieurs de ces onglets de code multi-langages, et que vous voulez synchroniser la sélection entre les instances de l'onglet, reportez-vous à la section Synchronisation des choix d'onglets.

Plugin remark npm2yarn de Docusaurus

L'affichage des commandes CLI à la fois pour NPM et Yarn est un besoin très courant, par exemple :

npm install @docusaurus/remark-plugin-npm2yarn

Docusaurus fournit un tel utilitaire dès le départ, vous évitant d'utiliser le composant Tabs à chaque fois. Pour activer cette fonctionnalité, installez d'abord le paquet @docusaurus/remark-plugin-npm2yarn comme ci-dessus, puis dans docusaurus.config.js, pour les plugins où vous avez besoin de cette fonctionnalité (doc, blog, pages, etc.), enregistrez-la dans l'option remarkPlugins. (Consultezla documentation de configuration pour plus de détails sur le format de configuration)

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
remarkPlugins: [
[require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
],
},
pages: {
remarkPlugins: [require('@docusaurus/remark-plugin-npm2yarn')],
},
blog: {
// ...
},
},
],
],
};

Et puis utilisez-le en ajoutant la clé npm2yarn au bloc de code :

```bash npm2yarn
npm install @docusaurus/remark-plugin-npm2yarn
```

L'utilisation de l'option {sync: true} permet de synchroniser tous les choix d'onglets. Comme le choix est stocké sous le même espace de nom npm2yarn, les différentes instances du plugin npm2yarn synchronisent également leurs choix.