Pular para o conteúdo principal

Contribuindo com esta documentação

Para contribuir com esta documentação, é possível seguir esta seção, e a documentação oficial do Docusaurus para mais detalhamento.

Clonando o projeto​

Em construção...

Estrutura do projeto​

1. /blog
2. /docs
3. /src
4. /static
5. docusarus.config.js

1 - Arquivos que serão exibidos no blog, caso utilizado. Não é utilizado nesta documentação.
2 - Todos os arquivos da documentação, seguindo uma estrutura. Um arquivo na raiz da pasta docs estará exibido na barra lateral, enquanto um arquivo com a localização /docs/Exemplo/ será exibido em uma seção expandível com nome "Exemplo"
3 - Utilizamos esta pasta como em qualquer outro projeto React. Podemos criar componentes, pastas, tipos e etc.
4 - Arquivos estáticos como imagens.
5 - Arquivo de configurações do Docusaurus, incluindo título, plugins e temas.

Recursos de documentação​

Tipos de arquivo​

É possível utilizar basicamente 2 tipos de arquivo na pasta /docs:

  • .md - Markdown básico. Pode ser usado em páginas mais simples.
  • .mdx - Markdown com suporte a HTML/Componentes React e a todos os recursos extendidos do Docusaurus.
Atenção

Uma desvantagem de arquivos .md/.mdx é a falta de auto-complete ou indicação de erros em código. Por isso, quando for utilizar HTML ou componentes React, é recomendado criar um componente na pasta /src/components.

Importando componentes em arquivos MDX​

Para importar componentes React em um arquivo .mdx, basta importarmos como em um arquivo JavaScript/TypeScript, apenas contando com o problema de não termos auto-complete:

import Component from "@site/src/components/Component";

<Component />
Dica

Para navegarmos por caminhos no projeto, podemos utilizar @site para nos referirmos a raiz do projeto. Então, para acessarmos algo na pasta src, nos referimos a ela com "@site/src".

Blocos de código​

<!-- Bloco de código TSX com titulo-->
```tsx title="Titulo do block"
    ...
```


<!-- Bloco de código com linhas numeradas-->
```tsx title="Bloco com linhas numeradas" showLineNumbers
    ...
    ...
    ...
```


<!-- Bloco de código com linhas numeradas e destaque na linha 3-->
```tsx {3} title="Bloco com linhas numeradas e destaque" showLineNumbers
    ...
    ...
    ...
```
Podemos envolver um bloco de código em arquivos .mdx com 3 acentos graves para abrir e mais 3 para fechar (`) um bloco de código, e especificar a linguagem do código dentro.
Resultados:

Tabs (Abas)​


import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';


<Tabs>
    <TabItem value='aba1' label='Aba 1' default>
        Aba 1
    </TabItem>
    <TabItem value='aba2' label='Aba 2'>
        Aba 2
    </TabItem>
</Tabs>

Admonitions (Textos em destaque)​

Para destacar um trecho importante de um texto ou observação, podemos usar Admonitions, blocos de texto com cor e ícone. Abrimos um admonition com ":::[categoria][título]" e ao final, fechamos com ":::". As categorias possíveis são:


:::note Notas
Anotações extras
:::
Nota

Anotações extras

Funcionalidades extras

Podemos combinar os admonitions com outros recursos do Docusaurus, como Tabs e blocos de código. Para ver mais, acesse a documentação oficial clicando aqui.

Configurações de página/seção​

Em cada página de docs, é possível adicionarmos o seguinte bloco no topo do arquivo para definirmos configurações da página:

---
slug: (Nome na url)
title: (Titulo)
description: (Descrição)
sidebar_label: (Titulo na barra lateral)
sidebar_position: (Posição na barra lateral)
---

Dentro de cada pasta de seção, é possível criarmos um arquivo _category_.json:

{
    "label": "(Nome da seção da barra lateral)",
    "position": (posição na barra lateral),
}