Como criar e hospedar um site de documentao para o seu projeto usando Hugo e Netlify

Introduo

Num post anterior dessa srie, ns vimos dicas e boas prticas para criar um bom readme para o seu projeto, e como organizar um set inicial de docs para cobrir o bsico.

Manter a documentao junto ao cdio fonte pode ser uma boa soluo em muitos casos, mas dependendo do tamanho do seu projeto e da quantidade de features ou oportunidades de customizao, ter um site de documentao dedicado pode ser uma melhor opo de longo termo para manter a documentao organizada, facilitando a busca por contedo e tambm criando um local "cannico" para referenciar e compartilhar.

Neste post, que a segunda parte da minha srie "Documentao 101", veremos como criar um site de documentao usando o gerador de sites esttico Hugo e hosped-lo gratuitamente na Netlify.

Nota: Esse tutorial tambm pode ser usado para criar um blog pessoal, escolhendo um tema mais adequado para um blog. O processo o mesmo!

Por que Hugo e Netlify?

H vrias formas de criar e hospedar uma documentao gratuitamente. Algumas combinaes que eu j experimentei:

• GitHub Pages: geralmente os docs ficam em uma branch separada no mesmo repositrio de projeto, pode ficar confuso com o tempo. Menos liberdade de customizao.
• Readthedocs + mkdocs: essa uma boa combinao usando o servio gratuito Readthedocs. O seu projeto ganha um subdomnio .readthedocs e voc tambm pode usar um domnio customizado. No geral uma tima soluo, mas de vez em quando tenho problemas com a atualizao automtica.
• Netlify + Hugo: minha combinao favorita no momento, porque alm de usar o Hugo (que um excelente gerador de sites estticos com muitas possibilidades de customizao), habilita voc a usar o recurso de "Deploy Preview" que eles oferecem como uma aplicao do GitHub. Sempre que uma PR aberta, um preview do deploy gerado com um endereo randmico e o bot da Netlify deixa um comentrio na PR com o link para o preview. Super til para fazer revises! O nico detalhe que com a Netlify voc vai querer usar um domnio customizado, caso contrrio o seu site ter um endereo randmico que no tem nada a ver com o projeto.

Instalando o Hugo

Hugo (you-go) um gerador de sites estticos bastante popular escrito em Go. Ele gera o contedo baseado em documentos markdown, que a maneira ideal de manter a sua documentao desacoplada de estilos e formatao. Uma seo de metadados adicionada no incio de cada post, de forma muito similar ao que temos no editor bsico de markdown aqui do DEV.

Voc pode hospedar gratuitamente o seu site criado com Hugo no Netlify e tambm em outras plataformas.

1. Download e Instalao

Primeiro, faa o download da verso mais recente do Hugo, escolhendo a verso adequada para o seu sistema. Na pgina de releases voc pode encontrar todos os pacotes disponveis. Evite usar o package manager do seu sistema (por exemplo, apt ou brew) j que as verses nesses repositrios geralmente estaro desatualizadas.

Para usurios Ubuntu, por exemplo, voc pode fazer o download do .deb e instalar usando dpkg:

sudo dpkg -i ~/Downloads/hugo_0.107.0_linux-amd64.deb

Aps completar a instalao, execute o comando hugo version para se certificar de que ele foi instalado com sucesso no seu sistema:

hugo version

Voc deve obter um output similar a este:

hugo v0.107.0-2221b5b30a285d01220a26a82305906ad3291880 linux/amd64 BuildDate=2022-11-24T13:59:45Z VendorInfo=gohugoio

2. Criando um novo projeto Hugo

Agora voc pode criar um novo site Hugo usando o comando seguinte. Para os exemplos nesse tutorial, eu usarei "mydocs" como nome do site.

hugo new site mydocs

Voc obter output similar ao seguinte:

Congratulations! Your new Hugo site is created in /home/erika/Projects/mydocs.Just a few more steps and you're ready to go:1. Download a theme into the same-named folder.   Choose a theme from https://themes.gohugo.io/ or   create your own with the "hugo new theme <THEMENAME>" command.2. Perhaps you want to add some content. You can add single files   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".3. Start the built-in live server via "hugo server".Visit https://gohugo.io/ for quickstart guide and full documentation.

Com a instalao bsica feita, voc agora pode comear a customizar o seu site.

3. Instalando um Tema

O site oficial do Hugo tem uma grande coleo de temas prontos para serem instalados e usados. Voc pode usar as categorias no menu da direita para filtrar os temas pela categoria "docs", assim encontrar os temas que so mais adequados para documentao.

Para esse tutorial, vamos usar o tema Geekdoc, o mesmo que utilizei para a documentao do yamldocs.

De forma geral, voc deve seguir as instrues de cada tema, j que alguns requerem dependncias bem especficas. No caso do Geekdocs, o processo de instalao bem simples e requer apenas que voc faa o download e descompacte o arquivo na pasta themes do Hugo. Voc pode fazer isso com os comandos seguintes:

cd mydocs/mkdir -p themes/hugo-geekdoc/curl -L https://github.com/thegeeklab/hugo-geekdoc/releases/latest/download/hugo-geekdoc.tar.gz | tar -xz -C themes/hugo-geekdoc/ --strip-components=1

O prximo passo editar o seu arquivo config.toml, que no momento est super bsico. Vamos adicionar algumas opes extras que so especficas desse tema e iro habilitar recursos adicionais.

Copie o seguinte contedo para o seu config.toml:

baseURL = "http://localhost"title = "My Documentation Site"theme = "hugo-geekdoc"pluralizeListTitles = false# Geekdoc required configurationpygmentsUseClasses = truepygmentsCodeFences = truedisablePathToLower = true# Required if you want to render robots.txt templateenableRobotsTXT = true# Needed for mermaid shortcodes[markup]  [markup.goldmark.renderer]    # Needed for mermaid shortcode    unsafe = true  [markup.tableOfContents]    startLevel = 1    endLevel = 9[taxonomies]   tag = "tags"

Ao finalizar, no esquea de salvar o arquivo.

Agora voc pode rodar o servidor de desenvolvimento do Hugo para visualizar o seu site:

hugo server -D

Voc dever obter uma pgina como esta:

Naturalmente, est um pouco vazia, j que no h nenhum documento indexado ainda. Primeiro, vamos dar uma olhada na estrutura de arquivos da sua instalao, para ter uma idia melhor de onde encontrar cada coisa:

. archetypes  default.md assets content data layouts public  categories  tags  index.xml  sitemap.xml resources  _gen static themes  hugo-geekdoc config.toml

Aqui esto alguns diretrios importantes para manter no seu radar:

• archetypes: esse diretrio contm templates para arquivos markdown que so gerados atravs do comando hugo new. Voc pode ter archetypes diferentes para cada tipo de contedo que voc publica.
• content: os arquivos de markdown com o contedo da sua documentao ou blog vivero aqui.
• layouts: aqui voc vai encontrar os arquivos HTML que formam a base do seu site. Esse diretrio estar vazio por padro, mas voc pode checar o diretrio themes/hugo-geekdoc/layouts e voc encontrar os layouts que esto sendo usados pelo seu site no momento. Voc vai notar que o tema replica a estrutura de diretrios da raiz, e isso importante pois o mecanismo usado para sobrescrever layouts a outros arquivos do tema. Para sobrescrever um layout do seu tema, voc s precisa criar um arquivo com o mesmo nome na pasta /layouts, e esses tero uma precedncia maior do que os layouts includos no tema.
• static: qualquer arquivo esttico, como logos / diagramas e ouras imagens usadas no site podem ser colocadas nesse diretrio, e ficaro disponveis publicamente.
• public: nesta pasta onde so gerados os arquivos HTML do seu site, a pasta que deve ser configurada como "document root" ao hospedar o seu site.

A documentao oficial (ingls) possui informaes mais detalhadas sobre a estrutura de diretrios usada pelo Hugo.

4. Fazendo o "Build" dos seus docs

Agora que o site est "up and running", voc pode comear a criar as suas pginas de documentao. Aqui onde o trabalho realmente acontece, ento no tenha pressa. Voc pode comear com uma pgina bsica do tipo "Getting Started" e ir melhorando sua documentao aos poucos. Em uma prxima parte dessa srie, vamos falar sobre planejamento e organizao de contedo.

Para criar uma nova pgina de documentao, voc pode usar o comando "hugo new". Esse comando ir assumir o tipo de contedo que voc est criando (archetype) baseado no caminho que voc definir como output. Por exemplo:

hugo new docs/getting-started.md

Content "/home/erika/Projects/mydocs/content/docs/getting-started.md" created

Abra o arquivo criado e adicione algum contedo para testes. Depois, faa um reloas da sua pgina e voc deve obter algo assim:

Voc vai notar que o markdown gerado tem um contedo pr definido, baseado no archetype do tipo "docs" que est definido pelo tema em `themes/hugo-geekdoc/archetypes/docs.md. Voc pode sobrescrever esse contedo pr definido criando um arquivo com o mesmo nome no diretrio "archetypes" na raiz do projeto.

Para aprender mais sobre archetypes, visite a documentao odicial.

Publicando seu site Hugo na Netlify

Como mencionado anteriormente, h vrias maneiras diferentes de hospedar um site Hugo gratuitamente. A maior vantagem da Netlify na minha opinio a funcionalidade de deploy preview que voc tem acesso atravs da interface do GitHub. Sempre que uma PR aberta, o bot da Netlify deixa um comentrio na PR com um link para prever as mudanas, assim facilitando o review.

Vamos agora ver como configurar tudo isso. Antes de avanar, assegure-se de comitar (e fazer o push) seu site Hugo para o GitHub ou GitLab, em um repositrio dedicado para ele. Isso um pr requisito para importar o seu site na Netlify.

1. Crie uma conta na Netlify

O primeiro passo ter uma conta (gratuita) na Netlify. Voc pode fazer o sign up com a sua conta do GitHub para facilitar a importao do seu projeto.

Depois de fazer sua conta e logar no site, voc ser direcionado para uma dashboard como essa:

2. Importe o seu projeto

Clique no boto "Add new site" para criar um novo projeto. Voc ter acesso a um menu dropdown. Escolha a primeira opo "Import an existing project" e siga as instrues para importar o seu projeto do GitHub / GitLab.

Voc pode precisar autorizar a Netlify para que tenha acesso aos seus repositrios. Depois disso, voc poder escolher qual repositrio quer importar. Escolha o repositrio com a sua instalao do Hugo e avance para a prxima pgina.

3. Configurando opes de deploy para sites Hugo

Nesta pgina voc vai encontrar as opes de configurao para o deploy. Para nossa sorte, a Netlify j detecta que se trata se um site Hugo e configura as opes padro. Graas ao fato de nosso tema ser simples e no usar node, por exemplo, podemos usar os valores de configurao padro fornecidos pela Netlify.

Clique em "Deploy Site" para finalizar o processo.

4. Preview do Projeto

Ao voltar para sua dashboard, voc vai notar que o seu novo site est no processo de "building", e j tem um subdominio randmico associado a ele. Voc poder adicionar um domnio prprio logo mais.

Agora voc pode acessar o site usando a url temporria e checar se ele est idntico sua verso local.

5. Configurando Deploy Preview

O recurso de "Deploy Preview" deve estar automaticamente habilitado para o seu projeto, mas voc precisar autorizar o app da Netlify no GitHub.

Para ter certeza de que essa feature est habilitada, acesse "Deploys" e ento "Continuous Deployment" no menu da esquerda. Voc deve encontrar uma seo como essa:

A documentao oficial explica em maiores detalhes como configurar essa feature.

6. Configurando um domnio prprio (opcional)

O passo final para ter o seu site publicado seria adicionar um domnio prprio. Apesar de ser opcional, extremamente recomendado, do contrrio o seu site ficar acessvel apenas pelo domnio randmico que no tem nada a ver com o projeto. Alm disso, com o domnio configurado voc ter um certificado SSL do Let's Encrypt para que seu site fique acessvel atravs de https - isso gerado automaticamente pelo Netlify.

Para configurar um domnio prprio, acesse o link "Set up a custom domain" que aparece no passo nmero 2 da seo "Set up your website" na sua dashboard. Voc pode usar um domnio ou subdominio que voc j possui, e tambm pode registrar um novo domnio diretamente da interface da Netlify. Siga as instrues e esteja ciente que pode levar algumas horas at que o site fique acessvel atravs do domnio customizado, dependendo da propagao do DNS.

Consulte a documentao oficial da Netlify para maiores detalhes em como configurar um domnio prprio com o seu site.

Concluso

Criar um site dedicado de documentao para o seu projeto uma soluo de longo termo que pode ajudar a aumentar a adoo e popularidade do projeto, facilitando a organizao e indexao da sua documentao.

Existem opes diferentes de sistemas e servios de hospedagem onde voc pode hospedar o seu site se documentao gratuitamente. Neste artigo, vimos como fazer isso usando o gerador de sites estticos Hugo, com hospedagem pela Netlify.

No prximo artigo dessa srie, veremos dicas prticas e recomendaes para planejamento e organizao da sua documentao, de forma a mant-la limpa e fcil de acompanhar.