O Nextra permite que você crie um site em minutos, por isso é perfeito para distribuir documentos para sua equipe.

Se você estiver familiarizado com o Next.js, poderá usá-lo para desenvolver um site de documentação com facilidade. A estrutura Nextra cuida do âmago da questão para você; tudo o que você precisa fazer é adicionar conteúdo Markdown ou HTML e dados YAML ou JSON.

Percorra estas etapas para criar um site de documentação usando Nextra, um gerador de site estático baseado em Next.js. Você instalará e configurará as dependências necessárias e aprenderá como adicionar novos documentos e páginas, escrever Markdown e incluir componentes React.

Requisitos para construir um site de documentos com o Nextra

Comece instalando o Node.js, caso ainda não o tenha feito. O versão mais recente do Node.js vem com npm, o gerenciador de pacotes do nó, que você precisará para instalar dependências para este projeto.

Além do Node.js, você precisará instalar git. Você precisa do Git para implantar o site nas páginas do GitHub, Netlify ou outro provedor de hospedagem. Você também precisará de um editor de código avançado, como o VS Code.

instagram viewer

Instalando o Nextra

Você pode usar um modelo de documentos nextra para inicializar um site de documentação. Inicie um prompt de comando e navegue até o diretório no qual deseja configurar seu projeto. Em seguida, execute o seguinte comando para inicializar o site de documentação:

git clone https://github.com/shuding/nextra-docs-template

Este comando fará o scaffold de um aplicativo dentro do diretório atual. Em seguida, execute o seguinte comando para instalar as dependências:

cd nextra-docs-template
npm instalar

Assim que a instalação for concluída, inicie o aplicativo. Faça isso executando o seguinte comando no seu terminal:

npm run dev

Este comando inicia um servidor de desenvolvimento em localhost: 3000. Siga o link em seu terminal para visualizar o site de documentação. A página inicial deve ficar assim:

Se você olhar no lado esquerdo da página, encontrará as páginas denominadas Introdução e Outra página. Abaixo desses links de página, você encontrará uma página chamada Satori, aninhada dentro do Avançado (uma pasta) diretório. Finalmente, na área de navegação, você encontrará links para o Sobre e Contato Páginas.

Para entender como essas páginas funcionam, primeiro você precisa entender como Next.js renderiza páginas.

Compreendendo a estrutura de diretórios

Como o Nextra usa o framework Next.js, ele renderiza cada arquivo no Páginas/ pasta como uma página separada.

Dentro de Páginas diretório, você encontrará quatro arquivos de modelo: sobre.mdx, avançado.mdx, outro.mdx, e index.mdx. Cada um desses arquivos corresponde a uma página do site; por exemplo, index.mdx corresponde à página inicial. O URL host local: 3000/sobre corresponde a sobre.mdx, e assim por diante.

Dentro Páginas, também há uma pasta chamada avançado, abrigando um único arquivo chamado satori.mdx. A URL para este arquivo será localhost: 3000/avançado/satori.

Observe como cada um desses arquivos termina com um .mdx extensão.

O que é MDX?

Se você tem experiência com React, você deve saber sobre JSX. Esta é uma linguagem semelhante a HTML que você pode usar para descrever a interface do usuário dos componentes do React.

MDX carrega, analisa e renderiza JSX em um documento Markdown. Graças ao MDX, você pode escrever componentes React e importá-los para seus documentos Markdown quando necessário. Os arquivos MDX terminam com a extensão .mdx e podem incluir Markdown e JSX.

O MDX permite combinar seu conhecimento de Markdown com React para criar componentes reutilizáveis. Você pode criar módulos CSS para estilizar os componentes. Isso ajuda a organizar seus componentes para melhorar a legibilidade e a manutenção.

Como Editar Páginas Existentes no Site de Documentação

Para editar uma página existente, basta abrir o arquivo correspondente e fazer as alterações. Os idiomas suportados são Markdown e JSX.

Por exemplo, abra o index.mdx arquivo e substitua o conteúdo por este:

# Bem-vindo à minha documentação
Estou feliz em vê-lo aqui. Obrigado
## Minhas redes sociais
Siga-me [Twitter](https://twitter.com/kingchuuks) e [LinkedIn](https://linkedin.com/in/kingchuks)

Este exemplo usa Markdown para formatar o conteúdo. Ele contém um cabeçalho de nível um, um cabeçalho de nível dois e dois links de mídia social.

Salve o arquivo e visite a página inicial do seu site de documentação. A página agora deve ficar assim:

Na parte inferior da página, você também pode encontrar a data da última atualização do documento.

Adicionando uma nova página

Antes de adicionar uma nova página, você precisa primeiro decidir se a página estará no Páginas/ diretório ou dentro de uma pasta dentro dele. Use pastas se quiser categorizar suas páginas ou desenvolver uma hierarquia.

Nesse caso, crie uma página autônoma no nível superior. Abra um arquivo chamado instalação.mdx no seu editor de código e cole o seguinte código Markdown nele:

# Guia de instalação
Siga este guia para instalar meu pacote em seu projeto
## 1. Instale o Node.js
Para instalar o Node.js, visite o
[Site de documentação do Node.js](https://nodejs.org/en/download)

Salve o arquivo e verifique o navegador. Você encontrará o rótulo de instalação no menu lateral. Ao clicar no link, o conteúdo do instalação.mdx renderiza na página:

Você pode alterar o rótulo e fazer outras configurações no arquivo _meta.json dentro do diretório pages. Para saber mais sobre isso, consulte o Organizar arquivos Seção de Documentação do Nextra.

Usando componentes de reação

Os arquivos MDX podem incluir JSX, que é a linguagem usada pelo React. Você pode criar um componente dentro da pasta de componentes e importá-lo em qualquer um dos documentos do seu site.

Você pode ver um exemplo de como incorporar componentes no Markdown no outro.mdx arquivo:

## Componente
importar {useState} de 'reagir'
importar estilos de '../components/counters.module.css'
export const Contador = () => { 
 const [contagem, setCount] = useState (0); 


 retornar( 


 Clicou {count} vezes


)
}

<Contador />

## Componentes Externos
importar contadores de '../components/counters'

<Contadores />

Este arquivo Markdown contém uma definição para o componente Counter. Em seguida importa o componente Contadores do componentes diretório.

Se você for usar o mesmo componente em seu site de documentação, é melhor criá-lo como um componente autônomo e importá-lo quando precisar.

Saiba mais sobre Markdown

Para criar conteúdo para seu site de documentação, você precisa saber como usar o Markdown. A boa notícia é que a sintaxe do Markdown é bastante fácil de aprender. Ao combinar seu conhecimento de Markdown com React, você pode criar sites de documentação realmente robustos.