Para sites leves, aplicativos e outros pequenos projetos, mais e mais desenvolvedores estão se voltando para geradores de sites estáticos através do WordPress ou outros sistemas de gerenciamento de conteúdo (CMS). Sites estáticos oferecem uma maneira simples e eficaz de criar sites e aplicativos que são rápidos, seguros e fáceis de manter.
Docusaurus é um desses geradores de sites estáticos – e está ganhando rapidamente popularidade na comunidade de desenvolvimento.
Neste artigo, faremos uma análise detalhada dos benefícios de usar o Docusaurus como seu gerador de site estático e por que ele está se tornando um favorito crescente entre os desenvolvedores.
O que é Docusaurus?
Docusaurus é um gerador de sites estáticos popular que utiliza React, uma das principais bibliotecas JavaScript, como sua biblioteca de interface do usuário (UI) para criação de páginas. Como outros geradores desse tipo, é fácil de configurar e modificar e, o mais importante, fornece tudo o que você precisa para começar a trabalhar com seu site estático.
Além disso, o que diferencia o Docusaurus é que ele é especialmente voltado para a criação e gerenciamento de sites onde o conteúdo é o protagonista. Ele permite que você crie um site completo, com recursos como blog, de forma rápida e fácil, destacando seu conteúdo desde o início.
Como o conteúdo é o foco com Docusaurus, é perfeito para criar sites de documentação como wikis. Ele também utiliza markdown, que é ideal tanto para colaboração quanto para armazenamento em um repositório git. Além disso, ele tem uma tonelada de recursos incríveis como i18n, pesquisa e temas personalizados, que discutiremos em mais detalhes mais adiante.
Aqui estão apenas alguns dos destaques que fazem do Docusaurus uma opção sólida:
- Construído usando React
- Suporte para MDX v1
- Suporte para incorporação de componentes React via markdown
- Versionamento de documentos
- Compatibilidade com Git, Crowdin e outros gerenciadores de tradução para tradução de documentos e implantação em massa ou individual.
Quem usa Docusaurus?
O Docusaurus foi criado pelo Facebook, então não é surpresa que ele esteja sendo usado atualmente por muitas grandes marcas e empresas em toda a internet.
Aqui estão apenas algumas das maiores marcas que usam Docusaurus hoje (com mais em breve, pois a popularidade do Docusaurus continua a crescer):
E outros estão se juntando às suas fileiras todos os dias.
Como instalar o Docusaurus
O Docusaurus é muito simples de instalar e requer apenas alguns minutos. Neste tutorial, estaremos construindo um site de documentação com um blog, e personalizaremos o visual do site.
E aqui está a parte mais legal: Levaremos menos de uma hora para fazer tudo funcionar.
Vamos começar!
Requisitos
Docusaurus requer o Node.js 16.14 ou mais recente. É um SSG de arquivo plano, o que significa que você não precisará de um banco de dados adicional.
Se você ainda não tem o Node.js 16.14+ disponível, você precisará começar instalando o Node.js ou atualizando sua versão atual. Então você pode passar para o processo de instalação do Docusaurus abaixo.
Também vamos usar o site Docusaurus de amostra deste repositório GitHub. Você pode usá-lo ou uma instalação limpa do Docusaurus para este tutorial.
Processo de instalação
Para iniciar o processo de instalação do Docusaurus, você precisa primeiro executar o seguinte comando:
npx create-docusaurus@latest classicIsso irá criar uma pasta para o seu projeto e esboçar o tema clássico dentro dela. O tema clássico já contém alguns recursos pré-configuradas, como um blog, páginas personalizadas e um framework CSS.
Após a instalação, você precisa então executar o seguinte comando para iniciar o servidor local:
npm startSe você quiser construir uma versão otimizada que esteja pronta para ser implantada, você deve executar esta versão no lugar:
npm run buildEstrutura
Uma vez instalada sua instância Docusaurus, você conseguirá abrir seu diretório de projetos e dar uma olhada no “esqueleto” do seu novo site.
Aqui está como é a estrutura do arquivo:
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lockHá alguns detalhes a serem observados em relação a alguns desses arquivos e pastas:
/blog: Contém todos os arquivos relacionados ao seu blog./docs: Contém todos os arquivos relacionados aos seus documentos. Você pode personalizar a ordem deles no arquivo sidebar.js./src: Contém todos os arquivos não documentais como páginas ou componentes personalizados./src/pages: Todos os arquivos JSX/TSX/MDX serão transformados em páginas./static: Arquivos estáticos que serão copiados para a pasta de compilação final.docusaurus.config.js: Arquivo de configuração do Docusaurus.packaged.json: Cada site Docusaurus é um aplicativo React, então aqui você encontrará todas as dependências e scripts que ele usa para o React.sidebar.js: Aqui você pode especificar a ordem dos documentos na barra lateral.
Personalizando sua instalação Docusaurus
Como você pode ver pela simplicidade de sua estrutura de arquivos, Docusaurus é fácil de usar e navegar. Da mesma forma, personalizar o seu site Docusaurus é uma tarefa fácil. Você pode abrir e editar estes arquivos usando seu editor de texto favorito ou IDE.
Vamos revisar algumas das opções de personalização que você terá logo de início.
Página inicial
A primeira coisa que você provavelmente estará louco para fazer é personalizar a página inicial padrão para exibir o seu próprio projeto. Felizmente, não é complicado fazer qualquer alteração que você queira na página inicial do Docusaurus.
Para alterar a página inicial, abra o arquivo src/pages/index.js e faça ajustes ali mesmo. É uma página React típica, então você pode alterá-la ou reconstruí-la alterando o conteúdo ou criando componentes React personalizados.
Arquivo de configuração
Próximo, vamos analisar o arquivo docusaurus.config.js e fazer algumas alterações importantes para à nossa instância.
Nome e descrição
No arquivo de configuração, você vai encontrar:
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',Basta alterar estes detalhes para atender às necessidades do seu site, e então salvar o arquivo.
Barra de navegação
Para editar sua barra de navegação, localize o item navbar.
Para nosso exemplo aqui, queremos adicionar um link para Kinsta, renomear o item “Tutorial” para “Documentação inicial”, e adicionar a logo da Kinsta.
Veja como faríamos:
navbar: {
title: 'Kinsta starters',
logo: {
alt: 'Kinsta Logo',
src: 'img/kinsta-logo-alpha-purple.png',
},
items: [
{
label: 'Kinsta starters',
to: '/docs/intro',
},
{to: '/blog', label: 'Blog', position: 'left'},
{
href: 'https://github.com/kinsta',
label: 'GitHub',
position: 'right',
},
],
},Rodapé
A personalização do rodapé no Docusaurus é composta de duas seções: o próprio conteúdo do rodapé, e os links do rodapé.
Conteúdo do rodapé
A maior parte do seu conteúdo de rodapé (não incluindo a lista de links) pode ser colocada no seu arquivo de rodapé do temaConfig.footer. Este é o local ideal para adicionar uma logo e um aviso de direitos autorais.
Aqui está como modificamos a configuração do rodapé:
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Kinsta Logo',
src: 'img/kinsta-logo.png',
href: 'https://kinsta.com',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`,
},
},
};Links para rodapés
Você pode modificar os links do rodapé da mesma forma que a barra de navegação superior: encontre a seção “footer” no arquivo docusaurus.config.js e edite para atender às suas necessidades.
Confira como fizemos a mudança na nossa seção footer :
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Kinsta starters',
to: '/docs/intro',
},
],
},
{
title: 'Talk with us',
items: [
{
label: 'Discord',
href: 'https://discord.gg/vjRPMhFaBA',
},
{
label: 'Support',
href: 'https://kinsta.com/kinsta-support/',
},
{
label: 'Twitter',
href: 'https://twitter.com/kinsta',
},
],
},
{
title: 'More',
items: [
{
label: 'Application Hosting',
href: 'https://kinsta.com/application-hosting/',
},
{
label: 'Database Hosting',
href: 'https://kinsta.com/database-hosting/',
},
{
label: 'WordPress Hosting',
href: 'https://kinsta.com/wordpress-hosting/',
},
{
label: 'DevKinsta',
href: 'https://kinsta.com/devkinsta/',
},
],
},
],
};Cores e CSS
O clássico preset para Docusaurus usa a estrutura Infima CSS. Com isto em mente, os criadores do Docusaurus fizeram uma ferramenta web muito útil para ajudá-lo a mudar as cores e outros elementos e declarações do CSS.
Uma vez que você tenha inserido suas preferências na página, a ferramenta irá gerar um arquivo custom.css – completo com um adorável conjunto de tons complementares – em questão de segundos. Você pode então copiar este novo arquivo CSS para o diretório /src/css do seu projeto para referência.
Documentação
Toda a documentação em seu novo site é armazenada na pasta /docs. É claro, você pode mudar o nome da pasta em docusaurus.config.js.
Basta criar os arquivos markdown no seu editor de texto ou HTML e colocá-los naquela pasta. Cada arquivo deve ser parecido com isso:
---
id: the-id
title: Title
---
# Rest of the documentBaseado no ID, Docusaurus constrói as URLs para os artigos dessa subpasta: yourdomain.com/docs/{id}
Também podemos criar subpastas se quisermos dividir nossa documentação em seções diferentes e lógicas. Entretanto, precisaremos fazer um pequeno trabalho adicional para que esses subdiretórios funcionem da maneira que esperaríamos.
Digamos que tenhamos criado uma nova pasta de documentos chamada Starters. Se atualizarmos a página inicial e clicarmos no novo link “Starters” que foi automaticamente adicionado à nossa barra lateral, receberemos um erro porque ainda não há uma página de índice em nossa nova pasta.
A maneira mais fácil de corrigir isso é criando um arquivo _category_.json que gerará o índice de todas as páginas armazenadas nesta pasta. Tudo o que precisamos fazer é adicionar o seguinte código:
{
"label": "Starters",
"position": 2,
"link": {
"type": "generated-index",
"description": "All Kinsta Starters"
},
};Como você pode ver, a barra lateral se regenera para combinar com a estrutura dos seus arquivos. Isso é porque o arquivo sidebar.js contém este tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
Se você preferir cuidar disso por conta própria, você pode simplesmente mudar isso para algo como:
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],Blog
Docusaurus inclui um módulo de blog elegante. Ter um blog junto com o seu site principal pode ser muito útil para informar sua base de usuários sobre as mudanças que estão acontecendo em seu projeto, ou para manter notas de projeto em andamento como um tipo de changelog.
Cada artigo consiste em uma parte de frontmatter, assim como esta:
---
slug: docusaurus-starter
title: Docusaurus Starter
authors: palmiak
tags: [starters, docusaurus]
---…e, claro, o próprio conteúdo. Ele também possui uma tag muito útil <!–truncate–> que ajuda a limitar o resumo do artigo exibido em todas as listagens de artigos.
Também é uma ótima ideia criar um arquivo authors.yml para os créditos. O arquivo parece com isso:
palmiak:
name: Maciek Palmowski
title: DevRel
url: https://github.com/palmiak
image_url: https://github.com/palmiak.pngGraças a este arquivo, você terá todos os dados do autor em um só lugar para fácil referência.
Como implantar seu site Docusaurus na Kinsta
Além de sites WordPress, aplicativos autônomos e bancos de dados, a Kinsta pode hospedar sites estáticos.
Isso significa que ela é perfeita para os seus sites Docusaurus — e para gerenciar todos os seus projetos web — diretamente do seu painel MyKinsta.
Certifique-se primeiro de enviar seu código para um provedor Git de sua preferência (Bitbucket, GitHub ou GitLab), e então siga estes passos para implantar seu site estático na Kinsta:
- Faça login ou crie uma conta para acessar o painel MyKinsta.
- Autorize a Kinsta com o seu provedor Git.
- Clique em “Sites Estáticos” na barra lateral à esquerda, e depois clique em “Adicionar Site“.
- Selecione o repositório e o branch de onde deseja fazer a implantação.
- Atribua um nome único ao seu site.
- Adicione as configurações de build no seguinte formato:
- Comando build:
npm run build - Versão do Node:
18.16.0 - Diretório de publicação:
build
- Comando build:
- Por fim, clique em “Criar site“.
Se você chegou até aqui sem erros, então parabéns — você implantou com sucesso seu site Docusaurus através da Kinsta!
Aqui está nossa primeira visita ao nosso site de amostra na Kinsta:
Como alternativa à Hospedagem de Site Estático, você pode optar por implantar seu site estático com a Hospedagem de Aplicativos da Kinsta, que oferece maior flexibilidade de hospedagem, uma gama mais ampla de benefícios e acesso a recursos mais robustos. Por exemplo, escalonamento, implantação personalizada usando um Dockerfile e análises abrangentes que englobam dados em tempo real e históricos.
Resumo
Com suas funcionalidades surpreendentemente poderosas, design amigável, navegação intuitiva e foco no conteúdo, não é difícil entender por que o Docusaurus é considerado uma ferramenta excelente para qualquer desenvolvedor que busca implantar e manter um site de documentação estática e/ou blog organizado de forma simplificada.
Assim que você preencher seu site com conteúdo de valor para seus visitantes, você notará recursos adicionais integrados que podem ajudar bastante. Por exemplo, as capacidades de SEO do Docusaurus são perfeitas para ajudá-lo a ganhar maior visibilidade com uma audiência mais ampla, enquanto você trabalha em outras técnicas para avançar nos rankings de SEO.
Já construiu algo com o Docusaurus? Compartilhe seus projetos e experiências conosco na seção de comentários abaixo.
Maciek é um desenvolvedor web atuando na Kinsta como Analista de Advocacia de Desenvolvimento. Quando não está trabalhando, ele se dedica principalmente à programação, à busca de notícias relevantes para suas newsletters.
Deixe um comentário