Ir para o conteúdo principal
Version: 2.0.0-beta.10 🚧

Blocos de código

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

Título do código

Você pode adicionar um título ao bloco de código adicionando a chave title após o idioma (deixe um espaço entre eles).

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

Destaque de sintaxe

Blocos de código são blocos de texto envolvidos por strings de 3 crases (backticks). Você pode verificar esta referência para especificações de MDX.

```jsx
console.log('Todo repositório deve vir com um mascote.');
```

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.

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'),
},
},
};

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.

Para adicionar syntax highlighting para qualquer um dos outros idiomas suportados pelo Prism, defina-o em uma variedade de idiomas adicionais.

Por exemplo, se você deseja adicionar destaque para a linguagem powershell:

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}`); // eslint-disable-line
});

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

Você pode colocar ênfase em certas linhas de código especificando intervalos de linha após a meta string de idioma (deixe um espaço após o idioma).

```jsx {3}
function HighlightSomeText(highlight) {
if (highlight) {
return 'This text is highlighted!';
}

return 'Nothing highlighted';
}
```
function HighlightSomeText(highlight) {
if (highlight) {
return 'Este texto está destacado!';
}

return 'Nada destacado';
}

Para fazer isso, o Docusaurus adiciona a classe docusaurus-highlight-code-line às linhas destacadas. Você precisará definir seu próprio estilo para este CSS, possivelmente em seu src/css/custom.css com uma cor de fundo personalizada que depende do tema de destaque de sintaxe selecionado. 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
.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);
}

/* Se você tiver um tema diferente de destaque de sintaxe para o modo escuro. */
html[data-theme='dark'] .docusaurus-highlight-code-line {
/* Cor que funciona com o tema escuro */
background-color: rgb(100, 100, 100);
}

Destaque de múltiplas linhas

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;
```
import React from 'react';

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

return <div>Foo</div>;
}

export default MyComponent;

Destacar com comentários

Você também pode usar comentários com highlight-next-line, highlight-start, e highlight-end para selecionar quais linhas são destacadas.

```jsx
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';
}
```
function HighlightSomeText(highlight) {
if (highlight) {
return 'Este texto está destacado!';
}

return 'Nada destacado';
}

function HighlightMoreText(highlight) {
if (highlight) {
return 'Este trecho está destacado!';
}

return 'Nada destacado';
}

Sintaxe de comentário suportada:

IdiomaSintaxe
JavaScript/* ... */ and // ...
JSX{/* ... */}
Python# ...
HTML<!-- ... -->

Se houver uma sintaxe que não seja suportada atualmente, estamos abertos para adicioná-la! Pull requests bem-vindos.

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(() => {
var 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.

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
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,
}}
/>
);

// Adicionar importações react-live que você precisa aqui
const ReactLiveScope = {
React,
. .React,
ButtonExample,
};

export default ReactLiveScope;

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

Editor ao vivo
Resultado
Loading...

Suporte para blocos de código multi-linguagem

Com MDX, você pode facilmente criar componentes interativos dentro da sua documentação, por exemplo, para exibir código em várias linguagens de programação e alternar entre elas usando um componente de abas.

Em vez de implementar um componente dedicado para blocos de código de suporte multi-linguagem, Nós implementamos um componente genérico Tabs no tema clássico para que você possa usá-lo também para outros cenários que não sejam de código.

O exemplo a seguir mostra como você pode ter guias de código multi-linguagem em seus documentos. Observe que as linhas vazias acima e abaixo de cada bloco de idioma é intencional. Esta é uma limitação atual do MDX, você precisa deixar linhas vazias em torno da sintaxe Markdown para o analisador MDX para saber que é sintaxe Markdown e não 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:

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.