Como criar um site estático para a sua documentação com base no MkDocs e MkDocs-Material
MkDocs é uma ferramenta desenvolvida para criar sites estáticos a partir de arquivos markdown brutos. Outras alternativas incluem Sphinx e Jekyll.
Utilizamos o MkDocs para criar o site estático do ISE Code-With Engineering Playbook a partir do conteúdo no repositório do GitHub. Em seguida, o implantamos no GitHub Pages.
Optamos pelo MkDocs por várias razões:
- É fácil de configurar e tem uma ótima aparência mesmo na versão padrão.
- Funciona bem com markdown, que é o formato que já usamos no Manual.
- Usa uma pilha Python, o que é amigável para muitos colaboradores do Manual.
Para efeito de comparação, o Sphinx gera principalmente documentações a partir do formato restructured-text (rst), e o Jekyll é escrito em Ruby.
Para configurar um site MkDocs, os principais recursos necessários são:
- Um arquivo
mkdocs.yaml, semelhante ao que temos no Manual. Este é o arquivo de configuração que define a aparência do site, a navegação, os plugins utilizados e muito mais. - Uma pasta chamada
docs(o valor padrão para o diretório) que contém os arquivos de origem da documentação. - Uma Ação do GitHub para gerar automaticamente o site (por exemplo, a cada commit na branch principal), semelhante a esta do Manual.
-
Uma lista de plugins usados durante a fase de construção do site. Especificamos os nossos aqui. E estes são os plugins que utilizamos:
- Material para MkDocs: Aparência e experiência de usuário baseadas no Material Design.
- pymdown-extensions: Melhora a aparência do conteúdo baseado em markdown.
- mdx_truly_sane_lists: Para definir o nível de recuo das listas sem precisar refatorar toda a documentação que já tínhamos no Manual.
A configuração local é muito fácil. Consulte Começando com o MkDocs para obter detalhes.
Para publicar o site, há uma integração fácil com o GitHub para armazenar o site como uma Página do GitHub.