O site com a documentação da nossa API de OpenBank usa Hugo, um framework open-source escrito em Golang para construção de sites estáticos.
O seu funcionamento é simples: a usuária escolhe um tema, insere conteúdo em arquivos de
formato markdown, edita um arquivo de configuração .toml
para promover customizações e voilà - 🐭🪄 a mágica
gopher acontece!
Este é o repositório principal do site da documentação e todo o conteúdo deve ser adicionado aqui, mas existem outros três repositórios relacionados ao projeto:
-
Tema: o tema que utilizamos é baseado no tema Docsy e pode ser encontrado nesse repositório aqui. Temos um fork para que seja possível promovermos alterações diretamente no estilo que não seriam possíveis através do arquivo de configuração. No nosso projeto, ele é consumido e referenciado como um submódulo git.
-
Site Sandbox: o código-fonte do site no ambiente de sandbox, que é gerado pelo código deste repositório + hugo a cada push na branch master, pode ser encontrado aqui. Importante ressaltar que o ambiente de sandbox é usado como pré-produção, a única diferença entre os dois é que os artigos sinalizados como
draft
serão publicados em sandbox. -
Site Produção: o código-fonte do site, que é gerado pelo código deste repositório + hugo a cada nova tag de release, pode ser encontrado aqui.
A url do site vai ser baseada no nome dos diretórios que ficam sob o diretório content
. Por isso, é importante que:
- espaços sejam representados por hífens
- acentos e pontuações não sejam utilizados
- os nomes sejam simples e representem aquilo que queremos ver na url
Os artigos devem receber o nome _index.pt.md
e devem estar dentro de uma pasta com o nome do título.
É possível alterar facilmente a imagem de capa localizada na homepage do site. Para isso, basta inserir
em /content/pt/
uma imagem que contenha a palavra background no nome (e.g cover-background.jpg
).
As seções da home podem ser customizadas diretamente em /content/pt/_index.html
, usando blocks do tipo feature
.
Cada seção precisa ter:
- Um ícone, que deve ser escolhido em Font Awesome {1}
- Um título {2}
- Descrição que aparecerá abaixo do título {3}
- Um botão de ação, com:
- Endereço para onde o botão levará {4.a} obs: caso o link seja interno, deve ser usado o endereço relativo
- Texto do botão {4.b}
{{% blocks/feature icon="{1}" title="{2}" %}}
<p>{3}</p><br>
<a href="{4.a}" class="btn btn-lg btn-secondary">{4.b}</a>
{{% /blocks/feature %}}
Se nenhuma providência for tomada, as seções e posts vão se organizar em ordem alfabética simples. Para impôr uma ordem
intencional, é necessário preencher o campo weight
do cabeçalho. O primeiro conteúdo que deve aparecer deve
ter weight
igual a 1, o segundo igual a 2, e assim por diante.
Mensagens de commit, nomes de branches e títulos de Pull Requests devem seguir os padrões informados no Guia de Estilo Git da Stone.
Para facilitar a colaboração, o fluxo de Git abaixo deve ser seguido:
A documentação é disponibilizada em dois ambientes: Sandbox e Produção. A atualização desses ambientes ocorre por meio de duas GitHub Actions, uma para cada ambiente. Essas ações rodam o Hugo e alimentam o repositório de interesse (Sandbox ou Produção) do site com as alterações - o que desencadeia a ação de atualização do site, que utiliza o GitHub Pages.
Temos a Action
que desencadeia uma nova construção do site sempre que a branch master deste repositório é atualizada. Em sandbox, usamos
a flag -D
para forçar os artigos que têm draft: true
no cabeçalho a serem publicados.
Temos a Action que desencadeia uma nova construção do site sempre que geramos uma tag de release neste repositório.
Como o projeto necessita de git submodules para o seu funcionamento, você deve os iniciar da seguinte forma:
-
Caso ainda não tenha clonado o projeto:
$ git clone --recurse-submodules https://github.com/stone-co/stone-api-docs.git
-
Caso já tenha clonado:
$ git submodule update --init --recursive
-
Digitar no terminal o seguinte comando:
$ hugo server
🔍 Obs: se você quiser forçar os drafts a serem publicados, utilize a flag
-D
-
No seu navegador, visitar o endereço localhost:1313 (ou o endereço que for informado no próprio terminal após rodar o comando acima)
-
Para parar, apertar
Ctrl + C
no terminal
Para mais informações sobre Hugo: getting started do Hugo e oficina de sites estáticos com hugo.
Baixe o executável do Hugo Windows 64 bits ou Windows 32 bits (este executável não é um instalador, é necessário fazer a instalação manual)
Descompacte o conteúdo do ZIP para a pasta C:\Hugo\bin
(pode ser na pasta que preferir)
Copie o caminho onde está o executável hugo.exe
para configurar seu sistema para reconhecer o comando Hugo. Para isso
você deve configurar a variável de ambiente PATH
seguindo os passos abaixo:
- Em Iniciar > Pesquisar, procure e selecione: Sistema (Painel de Controle)
- Clique no link Configurações avançadas do sistema.
- Clique em Variáveis de Ambiente. Na seção Variáveis do Sistema, localize a variável de ambiente
PATH
e selecione-a. Clique em Editar. Se a variável de ambientePATH
não existir, clique em Novo.- Na janela Editar Variável de Sistema (ou Nova Variável de Sistema), especifique o valor (
C:\hugo\bin\
) da variável de ambientePATH
. Clique em OK. Feche todas as janelas restantes clicando em OK.- Reabra o terminal e execute
$ hugo version
.
Outras formas de instalação podem ser encontradas aqui
Sugerimos que seja usado o Homebrew, mas no próprio site do Hugo há mais instruções (aqui).
Comando para instalar com Homebrew: $ brew install hugo
Use o package manager da sua distro/de sua preferência, instruções adicionais aqui
-
Para criar um novo conteúdo (na prática, vai ser criado um arquivo markdown que vai ser usado para gerar uma nova página html), deve-se digitar o seguinte comando:
$ hugo new content/nome-da-secao/nome-do-artigo/_index.pt.md
-
Em seguida, editar o arquivo que foi criado e adicionar o conteúdo que desejar após o fim do cabeçalho (sinalizado por
---
). O arquivo estará em:📂stone-api-docs └──📂content └──📂nome-da-secao └──📂nome-do-artigo └──📄_index.pt.md
-
Cada artigo tem um campo chamado
draft
no cabeçalho, que pode ter o valortrue
(caso seja ainda um rascunho) oufalse
(caso deva ser publicado). O default do campo étrue
, altere parafalse
para sinalizar que o artigo deve ser publicado no ambiente de Produção. 🚨 Mesmo que o campodraft
tenha o valortrue
, o artigo será publicado no ambiente de Sandbox!