Ir para o conteúdo principal
Version: Canary 🚧

Blocos de código

Blocos de código dentro da documentação são superpotentes 💪.

Título do código

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>;
}
```
http://localhost:3000
/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}

Destaque de sintaxe

Blocos de código são blocos de texto envolvidos por strings de 3 crases (backticks). You may check out this reference for the specifications of MDX.

```js
console.log('Every repo must come with a mascot.');
```

Use a meta string de idioma correspondente para o seu bloco de código, e o Docusaurus irá pegar o destaque de sintaxe automaticamente, alimentado por Prism React Renderer.

http://localhost:3000
console.log('Todo repositório deve vir com um mascote.');

Temas

Por padrão, o tema de destaque da sintaxe do Prism que usamos é Palenight. Você pode alterar isso para outro tema passando o campo theme no prism como themeConfig no seu docusaurus.config.js.

Por exemplo, se você preferir usar o tema de destaque dracula:

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

Because a Prism theme is just a JS object, you can also write your own theme if you are not satisfied with the default. 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.

Idiomas suportados

Por padrão, o Docusaurus vem com um subconjunto de linguagens comumente usadas.

caution

Algumas linguagens populares como Java, C#, ou PHP não estão ativadas por padrão.

To add syntax highlighting for any of the other Prism-supported languages, define it in an array of additional languages.

note

Each additional language has to be a valid Prism component name. 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.

For example, if you want to add highlighting for the PowerShell language:

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

Após adicionar adicionalIdiomas, reinicie o Docusaurus.

Se você quiser adicionar destaques para idiomas que ainda não são suportados pelo Prisma, você pode deslizar prisma-include-languages:

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

Ele vai produzir prism-include-languages.js na pasta src/theme. Você pode adicionar suporte para linguagens personalizadas editando prisma-include-languages.js:

src/theme/prism-include-languages.js
const prismIncludeLanguages = (Prism) => {
// ...

additionalLanguages.forEach((lang) => {
require(`prismjs/components/prism-${lang}`);
});

require('/path/to/your/prism-language-definition');

// ...
};

Você pode consultar as definições de idioma oficiais do Prisma quando você estiver escrevendo suas próprias definições de idioma.

Destaque de linha

Destacar com comentários

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 'This text is highlighted!';
}

return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
// highlight-start
if (highlight) {
return 'This range is highlighted!';
}
// highlight-end

return 'Nothing highlighted';
}
```
http://localhost:3000
function HighlightSomeText(highlight) {
if (highlight) {
return 'This text is highlighted!';
}

return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
if (highlight) {
return 'This range is highlighted!';
}

return 'Nothing highlighted';
}

Sintaxe de comentário suportada:

StyleSintaxe
C-style/* ... */ and // ...
JSX-style{/* ... */}
Bash-style# ...
HTML-style<!-- ... -->

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. If there's a comment style that is not currently supported, we are open to adding them! Pull requests bem-vindos. Note that different comment styles have no semantic difference, only their content does.

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. A cor indicada abaixo funciona para o tema padrão de destaque (Palenight), portanto, se você estiver usando outro tema, você terá que ajustar a cor de acordo.

/src/css/custom.css
: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

You can also specify highlighted line ranges within the language meta string (leave a space after the language). Para destacar várias linhas, separe os números das linhas por vírgulas ou use a sintaxe de intervalo para selecionar um pedaço de linhas. Esse recurso usa a biblioteca de parse-number-range e você pode encontrar mais sintaxe em seus detalhes do projeto.

```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;
```
http://localhost:3000
import React from 'react';

function MyComponent(props) {
if (props.isBar) {
return <div>Bar</div>;
}

return <div>Foo</div>;
}

export default MyComponent;
prefer comments

Prefer highlighting with comments where you can. By inlining highlight in the code, you don't have to manually count the lines if your code block becomes long. If you add/remove lines, you also don't have to offset your line ranges.

- ```jsx {3}
+ ```jsx {4}
function HighlightSomeText(highlight) {
if (highlight) {
+ console.log('Highlighted text found');
return 'This text is highlighted!';
}

return 'Nothing highlighted';
}
```

Below, we will introduce how the magic comment system can be extended to define custom directives and their functionalities. The magic comments would only be parsed if a highlight metastring is not present.

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. You can declare custom magic comments through theme config. For example, you can register another magic comment that adds a code-block-error-line class name:

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',
},
],
},
},
};
http://localhost:3000

In JavaScript, trying to access properties on null will error.

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: []. If there's no magic comment config, but Docusaurus encounters a code block containing a metastring range, it will error because there will be no class name to apply—the highlighting class name, after all, is just a magic comment entry.

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 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;
```
http://localhost:3000
import React from 'react';

function MyComponent(props) {
if (props.isBar) {
return <div>Bar</div>;
}

return <div>Foo</div>;
}

export default MyComponent;

Editor de código interativo

(Desenvolvido por React Live)

Você pode criar um editor de codificação interativo com o plugin @docusaurus/theme-live-codeblock. Primeiro, adicione o plugin ao seu pacote.

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

Você também precisará adicionar o plugin ao seu docusaurus.config.js.

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

Para usar o plugin, crie um bloco de código com live anexado à string meta do idioma.

```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>
);
}
```

O bloco de código será renderizado como um editor interativo. As alterações no código refletirão no painel de resultados ao vivo.

http://localhost:3000
Editor ao vivo
Resultado
Loading...

Importações

react-live and imports

Não é possível importar componentes diretamente do editor react-live code, você tem que definir importações disponíveis desde o início.

Por padrão, todas as importações React estão disponíveis. Se você precisar de mais importações disponíveis, deslize o âmbito de react-live:

npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope -- --eject
src/theme/ReactLiveScope/index.js
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;

O componente ButtonExample já está disponível para uso:

http://localhost:3000
Editor ao vivo
Resultado
Loading...

Imperative Rendering (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.

http://localhost:3000
Editor ao vivo
Resultado
Loading...

Using JSX markup in code blocks

Code block in Markdown always preserves its content as plain text, meaning you can't do something like:

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>
http://localhost:3000
Input: 1 2 3 4
Output: "366300745"
MDX is whitespace insensitive

MDX is in line with JSX behavior: line break characters, even when inside <pre>, are turned into spaces. You have to explicitly write the new line character for it to be printed out.

caution

Syntax highlighting only works on plain strings. Docusaurus will not attempt to parse code block content containing JSX children.

Suporte para blocos de código multi-linguagem

With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switch between them using a tabs component.

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.

O exemplo a seguir mostra como você pode ter guias de código multi-linguagem em seus documentos. 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>

E você receberá o seguinte:

http://localhost:3000
function helloWorld() {
console.log('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

Displaying CLI commands in both npm and Yarn is a very common need, for example:

npm install @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)

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: {
// ...
},
},
],
],
};

And then use it by adding the npm2yarn key to the code block:

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

Using the {sync: true} option would make all tab choices synced. Because the choice is stored under the same namespace npm2yarn, different npm2yarn plugin instances would also sync their choices.

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>
);
}
http://localhost:3000
/src/components/HelloCodeTitle.js
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.