Blocs de code
Les blocs de code dans la documentation sont super-puissants 💪.
Code title
You can add a title to the code block by adding a title
key after the language (leave a space between them).
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
```
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
Syntax highlighting
Les blocs de code sont des blocs de texte enveloppés par des chaînes de 3 backticks. You may check out this reference for the specifications of MDX.
```js
console.log('Chaque dépôt doit être accompagné d\'une mascotte.');
```
Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by Prism React Renderer.
console.log('Chaque dépôt doit être accompagné d'une mascotte.');
Theming
By default, the Prism syntax highlighting theme we use is Palenight. You can change this to another theme by passing theme
field in prism
as themeConfig
in your docusaurus.config.js.
For example, if you prefer to use the dracula
highlighting theme:
module.exports = {
themeConfig: {
prism: {
theme: require('prism-react-renderer/themes/dracula'),
},
},
};
Comme un thème Prism n'est qu'un objet JS, vous pouvez également écrire votre propre thème si vous n'êtes pas satisfait du thème par défaut. Docusaurus enhances the github
and vsDark
themes to provide richer highlight, and you can check our implementations for the light and dark code block themes.
Supported Languages
By default, Docusaurus comes with a subset of commonly used languages.
Certains langages populaires comme Java, C# ou PHP ne sont pas activés par défaut.
To add syntax highlighting for any of the other Prism-supported languages, define it in an array of additional languages.
Chaque langage supplémentaire doit être un nom de composant Prism valide. For example, Prism would map the language cs
to csharp
, but only prism-csharp.js
exists as a component, so you need to use additionalLanguages: ['csharp']
. You can look into node_modules/prismjs/components
to find all components (languages) available.
Par exemple, si vous voulez ajouter une coloration pour le langage PowerShell :
module.exports = {
// ...
themeConfig: {
prism: {
additionalLanguages: ['powershell'],
},
// ...
},
};
After adding additionalLanguages
, restart Docusaurus.
If you want to add highlighting for languages not yet supported by Prism, you can swizzle prism-include-languages
:
- npm
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic prism-include-languages
yarn swizzle @docusaurus/theme-classic prism-include-languages
pnpm run swizzle @docusaurus/theme-classic prism-include-languages
It will produce prism-include-languages.js
in your src/theme
folder. You can add highlighting support for custom languages by editing prism-include-languages.js
:
const prismIncludeLanguages = (Prism) => {
// ...
additionalLanguages.forEach((lang) => {
require(`prismjs/components/prism-${lang}`);
});
require('/path/to/your/prism-language-definition');
// ...
};
You can refer to Prism's official language definitions when you are writing your own language definitions.
Line highlighting
Highlighting with comments
You can use comments with highlight-next-line
, highlight-start
, and highlight-end
to select which lines are highlighted.
```js
function HighlightSomeText(highlight) {
if (highlight) {
// highlight-next-line
return 'Ce texte est surligné !';
}
return 'Rien de surligné';
}
function HighlightMoreText(highlight) {
// highlight-start
if (highlight) {
return 'Cette plage est surlignée !';
}
// highlight-end
return 'Rien de surligné';
}
```
function HighlightSomeText(highlight) {
if (highlight) {
return 'Ce texte est surligné !';
}
return 'Rien de surligné';
}
function HighlightMoreText(highlight) {
if (highlight) {
return 'Cette plage est surlignée !';
}
return 'Rien de surligné';
}
Syntaxe de commentaire supportée :
Style | Syntaxe |
---|---|
Style C | /* ... */ and // ... |
Style JSX | {/* ... */} |
Style Bash | # ... |
Style HTML | <!-- ... --> |
We will do our best to infer which set of comment styles to use based on the language, and default to allowing all comment styles. S'il y a une style de commentaire qui n'est pas actuellement supportée, nous sommes ouverts à les ajouter ! Les pull requests sont les bienvenues. Notez que les différents styles de commentaires ne présentent aucune différence sémantique, seul leur contenu en présente une.
You can set your own background color for highlighted code line in your src/css/custom.css
which will better fit to your selected syntax highlighting theme. 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.
:root {
--docusaurus-highlighted-code-line-bg: rgb(72, 77, 91);
}
/* If you have a different syntax highlighting theme for dark mode. */
[data-theme='dark'] {
/* Color which works with dark mode syntax highlighting theme */
--docusaurus-highlighted-code-line-bg: rgb(100, 100, 100);
}
If you also need to style the highlighted code line in some other way, you can target on theme-code-block-highlighted-line
CSS class.
Highlighting with metadata string
Vous pouvez également spécifier des plages de lignes en surbrillance dans la méta-chaîne du langage (laisser un espace après le langage). 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. This feature uses the parse-number-range
library and you can find more syntax on their project details.
```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;
Préférez la mise en surbrillance avec des commentaires lorsque vous le pouvez. En mettant en surbrillance le code, vous ne devez pas compter manuellement les lignes si votre bloc de code devient long. Si vous ajoutez/supprimez des lignes, vous n'avez pas non plus à décaler vos plages de lignes.
- ```jsx {3}
+ ```jsx {4}
function HighlightSomeText(highlight) {
if (highlight) {
+ console.log('Texte surligné trouvé');
return 'Ce texte est surligné !';
}
return 'Rien de surligné';
}
```
Ci-dessous, nous allons présenter comment le système de commentaire magique peut être étendu pour définir des directives personnalisées et leurs fonctionnalités. Les commentaires magiques ne seront analysés que si une mise en surbrillance n'est pas présente.
Custom magic comments
// highlight-next-line
and // highlight-start
etc. are called "magic comments", because they will be parsed and removed, and their purposes are to add metadata to the next line, or the section that the pair of start- and end-comments enclose.
Vous pouvez déclarer des commentaires magiques personnalisés à travers la configuration du thème. For example, you can register another magic comment that adds a code-block-error-line
class name:
- docusaurus.config.js
- src/css/custom.css
- myDoc.md
module.exports = {
themeConfig: {
prism: {
magicComments: [
// Remember to extend the default highlight class name as well!
{
className: 'theme-code-block-highlighted-line',
line: 'highlight-next-line',
block: {start: 'highlight-start', end: 'highlight-end'},
},
{
className: 'code-block-error-line',
line: 'This will error',
},
],
},
},
};
.code-block-error-line {
background-color: #ff000020;
display: block;
margin: 0 calc(-1 * var(--ifm-pre-padding));
padding: 0 var(--ifm-pre-padding);
border-left: 3px solid #ff000080;
}
In JavaScript, trying to access properties on `null` will error.
```js
const name = null;
// This will error
console.log(name.toUpperCase());
// Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')
```
En JavaScript, toute tentative d'accès aux propriétés de null
entraînera une erreur.
const name = null;
console.log(name.toUpperCase());
// Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')
If you use number ranges in metastring (the {1,3-4}
syntax), Docusaurus will apply the first magicComments
entry's class name. This, by default, is theme-code-block-highlighted-line
, but if you change the magicComments
config and use a different entry as the first one, the meaning of the metastring range will change as well.
You can disable the default line highlighting comments with magicComments: []
. S'il n'y a pas de configuration de commentaire magique, mais que Docusaurus rencontre un bloc de code contenant une plage de métastring, il commettra une erreur parce qu'il n'y aura pas de nom de classe à appliquer - le nom de classe de métastring, finalement, n'est qu'une entrée de commentaire magique.
Every magic comment entry will contain three keys: className
(required), line
, which applies to the directly next line, or block
(containing start
and end
), which applies to the entire block enclosed by the two comments.
Using CSS to target the class can already do a lot, but you can unlock the full potential of this feature through swizzling.
- npm
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic CodeBlock/Line
yarn swizzle @docusaurus/theme-classic CodeBlock/Line
pnpm run swizzle @docusaurus/theme-classic CodeBlock/Line
The Line
component will receive the list of class names, based on which you can conditionally render different markup.
Line numbering
You can enable line numbering for your code block by using showLineNumbers
key within the language meta string (don't forget to add space directly before the key).
```jsx {1,4-6,11} showLineNumbers
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;
Interactive code editor
(Powered by React Live)
You can create an interactive coding editor with the @docusaurus/theme-live-codeblock
plugin. Tout d'abord, ajoutez le plugin à votre package.
- npm
- Yarn
- pnpm
npm install --save @docusaurus/theme-live-codeblock
yarn add @docusaurus/theme-live-codeblock
pnpm add @docusaurus/theme-live-codeblock
You will also need to add the plugin to your docusaurus.config.js
.
module.exports = {
// ...
themes: ['@docusaurus/theme-live-codeblock'],
// ...
};
To use the plugin, create a code block with live
attached to the language meta string.
```jsx live
function Clock(props) {
const [date, setDate] = useState(new Date());
useEffect(() => {
const timerID = setInterval(() => tick(), 1000);
return function cleanup() {
clearInterval(timerID);
};
});
function tick() {
setDate(new Date());
}
return (
<div>
<h2>It is {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.
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
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope -- --eject
yarn swizzle @docusaurus/theme-live-codeblock ReactLiveScope --eject
pnpm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope -- --eject
import React from 'react';
const ButtonExample = (props) => (
<button
{...props}
style={{
backgroundColor: 'white',
color: 'black',
border: 'solid red',
borderRadius: 20,
padding: 10,
cursor: 'pointer',
...props.style,
}}
/>
);
// Add react-live imports you need here
const ReactLiveScope = {
React,
...React,
ButtonExample,
};
export default ReactLiveScope;
The ButtonExample
component is now available to use:
Rendu impératif (noInline)
The noInline
option should be used to avoid errors when your code spans multiple components or variables.
```jsx live noInline
const project = 'Docusaurus';
const Greeting = () => <p>Hello {project}!</p>;
render(<Greeting />);
```
Unlike an ordinary interactive code block, when using noInline
React Live won't wrap your code in an inline function to render it.
You will need to explicitly call render()
at the end of your code to display the output.
Using JSX markup in code blocks
Le bloc de code dans Markdown conserve toujours son contenu en texte brut, ce qui signifie que vous ne pouvez pas faire quelque chose comme :
type EditUrlFunction = (params: {
// This doesn't turn into a link (for good reason!)
version: <a href="/docs/versioning">Version</a>;
versionDocsDirPath: string;
docPath: string;
permalink: string;
locale: string;
}) => string | undefined;
If you want to embed HTML markup such as anchor links or bold type, you can use the <pre>
tag, <code>
tag, or <CodeBlock>
component.
<pre>
<b>Input: </b>1 2 3 4{'\n'}
<b>Output: </b>"366300745"{'\n'}
</pre>
Input: 1 2 3 4
Output: "366300745"
MDX is in line with JSX behavior: line break characters, even when inside <pre>
, are turned into spaces. Vous devez écrire explicitement le caractère saut de ligne pour qu'il soit imprimé.
La coloration syntaxique ne fonctionne que sur des chaînes de caractères simples. Docusaurus ne tentera pas d'analyser le contenu du bloc de code contenant des fils JSX.
Multi-language support code blocks
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.
Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a general-purpose <Tabs>
component in the classic theme so that you can use it for other non-code scenarios as well.
L'exemple suivant montre comment vous pouvez avoir des onglets de code multi-language dans vos documents. Note that the empty lines above and below each language block are intentional. This is a current limitation of MDX: you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not 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 :
- JavaScript
- Python
- Java
function helloWorld() {
console.log('Hello, world!');
}
def hello_world():
print("Hello, world!")
class HelloWorld {
public static void main(String args[]) {
System.out.println("Hello, World");
}
}
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.
Docusaurus npm2yarn remark plugin
L'affichage des commandes CLI à la fois pour npm et Yarn est un besoin très courant, par exemple :
- npm
- Yarn
- pnpm
npm install @docusaurus/remark-plugin-npm2yarn
yarn add @docusaurus/remark-plugin-npm2yarn
pnpm add @docusaurus/remark-plugin-npm2yarn
Docusaurus provides such a utility out of the box, freeing you from using the Tabs
component every time. To enable this feature, first install the @docusaurus/remark-plugin-npm2yarn
package as above, and then in docusaurus.config.js
, for the plugins where you need this feature (doc, blog, pages, etc.), register it in the remarkPlugins
option. (See Docs configuration for more details on configuration format)
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
remarkPlugins: [
[require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
],
},
pages: {
remarkPlugins: [require('@docusaurus/remark-plugin-npm2yarn')],
},
blog: {
remarkPlugins: [
[
require('@docusaurus/remark-plugin-npm2yarn'),
{converters: ['pnpm']},
],
],
// ...
},
},
],
],
};
And then use it by adding the npm2yarn
key to the code block:
```bash npm2yarn
npm install @docusaurus/remark-plugin-npm2yarn
```
Configuration
Option | Type | Par défaut | Description |
---|---|---|---|
sync | boolean | false | S'il faut synchroniser le convertisseur sélectionné sur tous les blocs de code. |
converters | array | 'yarn' , 'pnpm' | La liste des convertisseurs à utiliser. L'ordre des convertisseurs est important, car le premier convertisseur sera utilisé comme choix par défaut. |
Usage in JSX
Outside of Markdown, you can use the @theme/CodeBlock
component to get the same output.
import CodeBlock from '@theme/CodeBlock';
export default function MyReactPage() {
return (
<div>
<CodeBlock
language="jsx"
title="/src/components/HelloCodeTitle.js"
showLineNumbers>
{`function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}`}
</CodeBlock>
</div>
);
}
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
The props accepted are language
, title
and showLineNumbers
, in the same way as you write Markdown code blocks.
Although discouraged, you can also pass in a metastring
prop like metastring='{1-2} title="/src/components/HelloCodeTitle.js" showLineNumbers'
, which is how Markdown code blocks are handled under the hood. However, we recommend you use comments for highlighting lines.
As previously stated, syntax highlighting is only applied when the children is a simple string.