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

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.

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

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.

```jsxfunction 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 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>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
SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

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 aquiconst ReactLiveScope = {  React,  . .React,  ButtonExample,};
export default ReactLiveScope;

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

Editor ao vivo
Resultado
SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

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  defaultValue="js"  values={[    { label: 'JavaScript', value: 'js', },    { label: 'Python', value: 'py', },    { label: 'Java', value: 'java', },  ]}><TabItem value="js">
```jsfunction helloWorld() {  console.log('Olá mundo!');}```
</TabItem><TabItem value="py">
```pydef hello_world():  print 'Olá mundo!'```
</TabItem><TabItem value="java">
```javaclass HelloWorld {  public static void main(String args[]) {    System.out.println("Olá mundo");  }}```
</TabItem></Tabs>

E você receberá o seguinte:

function helloWorld() {  console.log('Olá mundo!');}

Você pode querer implementar sua própria abstração de <MultiLanguageCode /> se você encontrar a abordagem acima demais demais. Poderemos apenas implementar uma no futuro por conveniência.

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.