Markdown Features
Docusaurus uses GitHub Flavored Markdown (GFM). Descubra aqui mais sobre os campos específicos do Docusaurus ao escrever em Markdown.
Cabeçalhos Markdown
Documentos
Os documentos usam os seguintes campos no cabeçalho Markdown, que precisa estar dentro de duas linhas ---, uma a cada lado:
id: Uma id única do documento. Se esse campo não estiver presente, o id do documento será então o nome de seu arquivo (sem a extensão).
title: O título do seu documento. Se esse campo não estiver presente, o id do documento será então usado como title.
hide_title: Controla se o título no começo do documento será ocultado ou não.
sidebar_label: The text shown in the document sidebar and in the next/previous button for this document. Se esse campo não estiver presente, o title do documento será então usado como sidebar_label.
Por exemplo:
---
id: doc1
título: Meu Documento
sidebar_label: Documento
---
Documentos versionados, quando são copiados, têm seus IDs alterados para incluírem o número da versão. O novo id se torna version-${versão}-${id}, onde ${versão} é o número de versão daquele documento e ${id} é o id original dele. Além disso, os documentos versionados recebem um campo original_id com o ID original do documento.
Por exemplo:
---
id: version-1.0.0-doc1
title: Meu documento
sidebar_label: Documento
original_id: doc1
---
custom_edit_url: O link para editar este documento. Se este campo não estiver presente, então o link para editar o documento será o do campo opcional editUrl do arquivo siteConfig.js. See siteConfig.js docs for more information.
Por exemplo:
---
id: doc-markdown
title: Recursos Markdown
custom_edit_url: https://github.com/facebook/docusaurus/edit/docs/api-doc-markdown.md
---
Posts do Blog
Os posts de blog usam os seguintes campos no cabeçalho Markdown, que precisa estar dentro de duas linhas ---, uma a cada lado:
title: O título do post.
author: O autor do post. Se este campo for omitido, nenhum nome de autor será mostrado.
authorURL: O link para o qual o usuário será levado quando ele clicar no nome do autor. Se este campo for omitido, o nome do autor não será um link, e sim apenas texto.
authorFBID: O ID do Facebook do autor, usado apenas para obter a foto de perfil que será mostrada ao lado do nome dele no post. Se este campo for omitido, nenhuma foto de perfil será mostrada no post.
Por exemplo:
---
title: Meu primeiro post de blog
author: Frank Li
authorURL: http://twitter.com/franchementli
authorFBID: 100002976521003
---
Recursos adicionais
O Docusaurus oferece suporte a alguns recursos adicionais ao escrever sua documentação em Markdown.
Adicionando links para outros documentos
Você pode usar URLs relativos para outros arquivos da documentação, os quais serão automaticamente convertidos para os links dos arquivos HTML correspondentes assim que forem renderizados.
Exemplo:
[Isto é um link para outro documento](outro-documento.md)
Esse código Markdown será automaticamente convertido para um link que aponta para /docs/outro-documento.html (ou para a versão traduzida/versionada correspondente a ele) assim que ele for renderizado.
Isso pode ser útil para quando você quiser navegar pela documentação no GitHub, já que lá esses links funcionam já de cara (dentro do GitHub). No entanto, os documentos conterão os links HTML corretos quando forem renderizados para o site.
Adicionando links para imagens ou outros assets
Links para assets estáticos podem ser criados da mesma maneira que links para outros documentos: usando URLs relativos. Os assets estáticos usados em documentos e posts de blog precisam estar dentro dos diretórios docs/assets e website/blog/assets, respectivamente. Os links em Markdown serão convertidos de forma a apontar para os caminhos de arquivo corretos, para que esses caminhos funcionem para documentações em todos os idiomas e versões.
Exemplo:
Gerando um índice
Você pode criar uma lista de links gerada automaticamente, que pode ser útil como um índice para a documentação de uma API.
No seu arquivo Markdown, adicione uma linha com o texto ``. Escreva sua documentação usando títulos h3 para cada função dentro de um bloco de código. These will be found by Docusaurus and a list of links to these sections will be inserted at the text <AUTOGENERATED_TABLE_OF_CONTENTS>.
Exemplo:
### `docusaurus.function(a, b)`
Texto descrevendo a função
### `docdoc(file)`
Texto descrevendo a função
Isso criará um índice das funções:
- `docusaurus.function(a, b)`
- `docdoc(file)`
E cada função na lista será um link para sua seção correspondente na página.
Language-specific Code Tabs
Display code in multiple programming languages using code tabs. First, mark the start and end of a code tabs group, by using <!-- DOCUSAURUS_CODE_TABS --> and <!-- END_DOCUSAURUS_CODE_TABS --> respectively in your markdown. Then start each tab with <!--[TAB_TITLE]-->.
Adding the following code to your Markdown file:
produces this:
console.log('Hello, world!');
print('Hello, world!')
#include <stdio.h>
int main() {
printf("Hello World!");
return 0;
}
program HelloWorld;
begin
WriteLn('Hello, world!');
end.
Realce de sintaxe
O realce de sintaxe é ativado por padrão em blocos de código cercados. A linguagem já deve ser detectada automaticamente, porém às vezes você pode obter melhores resultados ao se especificar ela. Você pode fazer isso usando uma string informativa, logo após os três acentos graves (também conhecidos como backticks) de abertura. O seguinte exemplo em JavaScript...
```js
ReactDOM.render(<h1>Olá, mundo!</h1>, document.getElementById('root'));
```
...seria renderizado com realce de sintaxe assim:
ReactDOM.render(<h1>Olá, mundo!</h1>, document.getElementById('root'));
O realce de sintaxe é realizado pelo Highlight.js usando o tema especificado no seu arquivo siteConfig.js, lá na chave highlight:
{
...
highlight: {
theme: 'default'
}
...
}
Você pode conferir a lista completa de temas compatíveis no diretório styles do Highlight.js.
Registrando linguagens adicionais
Por mais que o Highlight.js já venha compatível com várias linguagens populares, você pode encontrar a necessidade de registrar suporte adicional para uma linguagem que não esteja entre elas. Pensando nisso, nós liberamos uma válvula de escape ao expor a constante hljs como parte da chave de configuração highlight. Isso, por sua vez, permite que você chame registerLanguage:
{
...
highlight: {
theme: 'default',
hljs: function(hljs) {
hljs.registerLanguage('galacticbasic', function(hljs) {
// ...
});
}
}
}
Usando o Prism como realçador de sintaxe adicional
Você também pode optar por usar o Prism para realçar a sintaxe de certas linguagens disponíveis nesta lista. Inclua-as no campo usePrism do seu siteConfig.js
Exemplo:
// siteConfig.js
usePrism: ['jsx']
Observe que o bloco de código abaixo usa o realce de sintaxe do Prism para a linguagem JSX.
class Exemplo extends React.Component {
render() {
return (
<View style={{flex: 1, alignItems: 'center', justifyContent: 'center'}}>
<Text>Docusaurus</Text>
<Button
title="Clique aqui"
onPress={() => this.props.navigation.push('Docusaurus')}
/>
</View>
);
}
}
Adding Copy Code Buttons
Docusaurus allows for adding buttons to copy the code within fenced code blocks. Please follow the instructions here to add "Copy" buttons to your code blocks.