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 [email protected] 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 é perfeito para seus sites Docusaurus – e para gerenciar todos os seus projetos web – diretamente do seu painel MyKinsta.
Após implantar seu aplicativo, você poderá revisar as análises em tempo real e históricas, incluindo métricas como uso de largura de banda, tempo de build e execução, uso de CPU e memória. O processo de implantação através do MyKinsta leva apenas alguns minutos, do início ao fim.
- Uso de largura de banda
- Tempo de build
- Tempo de execução
- Uso de CPU
- Uso de memória
- Do início ao fim, o processo de implantação pelo MyKinsta leva apenas alguns minutos.
Vamos começar!
Pré-requisitos: Configurando seu projeto Docusaurus
Para hospedar seu projeto Docusaurus na Plataforma de Hospedagem de Aplicativos da Kinsta, você precisará:
- Inclua um campo de nome no seu arquivo package.json. (Isso pode ser qualquer coisa e não afetará sua implantação.)
- Inclua um script de build em seu arquivo package.json. (Seu projeto Docusaurus já deve incluir isso.)
- Instale o pacote serve npm e defina o script de início para servir o build.
Uma vez que estes são verificados, você pode passar para a implantação efetiva do seu site.
Implantando seu projeto Docusaurus
Siga estes simples passos para conectar-se à sua conta GitHub e lançar seu site Docusaurus:
- Entre na sua conta MyKinsta e navegue até a aba Aplicativos no menu do lado esquerdo.
- Clique no botão azul Adicionar serviço e escolha Aplicativos a partir do menu suspenso.
A aba de Aplicativos no painel MyKinsta com o cursor do mouse passando sobre a opção “aplicativos” após clicar no botão azul “Adicionar serviço”. - Caso você ainda não tenha conectado a sua conta do GitHub ao MyKinsta, um modal será exibido para incentivá-lo a fazer isso. Basta clicar no botão “Continuar com o GitHub” para prosseguir.
Modal com “Integração com o GitHub”. Botões “Cancelar” e “Continuar com o GitHub”. - Uma nova janela será aberta, solicitando sua permissão para autorizar Kinsta a acessar e gerenciar seus recursos do GitHub. Certifique-se de estar conectado à conta correta no GitHub e clique no botão verde “Autorizar Kinsta” perto da parte inferior.
Modal de autorização do GitHub: “Kinsta gostaria de ter permissão para fazer o seguinte: Verificar sua identidade GitHub (kinstauser); Saber quais recursos você pode acessar; Agir em seu nome”. Botões: “Cancelar” (cinza) e “Autorizar Kinsta” (verde). - Agora você chegou ao assistente de integração do GitHub. Este é o último passo antes que você possa implantar o seu site. Considere cuidadosamente os campos apresentados e preencha de acordo com a configuração do seu GitHub e os requisitos do seu projeto. Se você tem um Dockerfile em seu repositório, você pode usar isso para configurar a imagem do contêiner; caso contrário, Kinsta irá automaticamente configurar uma imagem do contêiner para você. Note que você pode precisar editar suas permissões do GitHub antes que você possa prosseguir, particularmente se esta for sua primeira implantação através da Kinsta.
O novo assistente de aplicativos no MyKinsta mostrando a mão do mouse passando sobre a opção dropdown “Edit GitHub permissions” para o campo “GitHub repository”. Você pode escolher se concede à Kinsta acesso a todos os repositórios, ou apenas a repositórios específicos. Estas permissões podem ser ajustadas a qualquer momento a partir das configurações da sua conta no GitHub.
A seção “Permissões” do GitHub, mostrando duas opções na seção “Acesso a repositórios”: “Todos os repositórios” ou “Somente repositórios selecionados”. - Após você ter feito suas seleções e confirmado suas escolhas, serão mostrados seus detalhes de implantação, assim como as opções de Change settings ou Redeploy.
A página “Deployment details” no MyKinsta mostrando informações referentes ao aplicativo implantado, incluindo o nome da branch implantada, número de commit, mensagem de commit, tempos de implantação e a localização do centro de dados selecionado. Aqui também é onde você verá quaisquer erros que ocorreram durante a implantação, com detalhes sobre o que causou a falha, para que você possa resolvê-la facilmente. Se você se encontrar lutando para corrigir o problema, orientações adicionais sobre erros de implantação podem ser encontradas na documentação da Kinsta.
Um erro intitulado “processo de build falhou” junto com “Tipo de falha de build desconhecido” acima de um painel de detalhes que lista os erros individuais que contribuíram para a falha.
Se você chegou até aqui sem erros, então parabéns – você acabou de implantar com sucesso seu site Docusaurus através da Kinsta! Seu aplicativo (ou seja, seu site estático) está disponível assim que você tiver completado o assistente. Você pode visualizá-lo na URL do seu aplicativo, que é comumente https://your-docusaurus-site.kinsta.app.
Aqui está nossa primeira visita ao nosso site de amostra na Kinsta:
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.
Deixe uma resposta