Como Instalar MkDocs No Debian 11

Ouvir tutorial

MkDocs é um gerador de site estático rápido, simples e absolutamente lindo que é voltado para a documentação do projeto de construção. Os arquivos de origem da documentação são gravados em Markdown e configurados com um único arquivo de configuração YAML.

Distribuição utilizada: Debian 11

Pacotes utilizados no tutorial

Instalação MkDocs

Verificando a versão instalada

Crie um novo projeto chamado mkdocs e construa um novo site

Verifique se os seguintes arquivos foram criados com sucesso

Como estou rotando em um VM de lab vou verificar qual o IP recebi por DHCP na interface e iniciar o serviço.

Vamos iniciar o serviço de forma manual apenas para realizar um teste.

Agora abra no seu navegador http://IP:8000

No terminal para finalizar o mkdocs precione CRTL+C
Particular mente eu não gosto do tema padrão (mkdocs) então você pode optar em alterar editando /mkdocs/mkdocs.yml

Gosto dos temas:

material

readthedocs

Edite e escolha o seu favorito (existe outros temas) também usarei o idioma português.

Inicie mkdocs com systemd
Por padrão se você iniciar o mkdocs serve será iniciar em seu ip de loopbak localhost, a ideia aqui vai ser iniciar o mesmo como o systemd e em seguida fazer um proxy com nginx.

Para executar MKDocs como um serviço, crie um arquivo de serviço no systemd

Adicione:

Recarregue daemon, em seguiga habilitamos nosso novo serviço mkdocs para inicia com o boot do sistema, e inicializamos o mesmo.

Verifique se o mesmo incializou

NGIX PROXY

Se você esta pensando para que diabos instalar um serviço web se poderia rodar o mkdocs na porta 80 e iniciar-lo diretamenta para o IP da interface em vez de inicia-lo para apenas o ip de localhost (127.0.0.1), a resposta é: Acredito que você não terá um servido so para isso, logo a idiea do nginx é tornar a aplicação acessivel via domínio por exemplo, ou não confilhar com ninguém, então cada caso é um caso. Aqui é apenas uma ideia!

Vou utilizar da conf default

Adicione e altere para suas necessidades

Agora basta acessar ex. http://mkdocs.remontti.com.br

Para criação de documentos recomendo você ler como funciona Markdown, e veja o guia do mkdocs. Leia também https://daringfireball.net/projects/markdown/syntax e https://www.markdownguide.org

Um ótimo editor Markdown online é o Stackedit que pode auxilhar na contrução dos seus arquivos.

Vou fazer algobem simples de exemplo:

Vou cirar o menu de navegação e apontar para cada arquivo correspondente que ficam no diretório /opt/mkdocs/docs. Sempre que alterar as configurações do mkdocs.ym será necessário reiniciar o serviço.

Reinicie o mkdocs

Agora vamos editar/criar nossos arquivos.

# vim /opt/mkdocs/docs/index.md


Se quiser fazer uma doação para o café ficarei muito feliz pelo seu reconhecimento!

Se não puder doar pode deixar seu agradecimento nos comentário também ficarei feliz em saber que ajudei. Se tiver qualquer pergunta deixe-a também. Se preferir entrar em Contato clique aqui.

Fontes:
https://www.mkdocs.org/
https://github.com/mkdocs/mkdocs/

Rudimar Remontti

Trabalho atualmente como Gerente de Redes em um Provedor de Internet no Rio Grande do Sul.

Você pode gostar...

Deixe um comentário

O seu endereço de e-mail não será publicado.