Como Instalar MkDocs No Debian 11
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
|
1 |
# apt install wget net-tools tree python3-pip vim |
Instalação MkDocs
|
1 2 |
# apt install mkdocs # pip3 install mkdocs-material mkdocs[i18n] |
Verificando a versão instalada
|
1 |
# mkdocs --version |
|
1 |
mkdocs, version 1.1.2 from /usr/lib/python3/dist-packages/mkdocs (Python 3.9) |
Crie um novo projeto chamado mkdocs e construa um novo site
|
1 2 3 4 |
# cd /opt/ # mkdocs new mkdocs # cd /opt/mkdocs # mkdocs build |
Verifique se os seguintes arquivos foram criados com sucesso
|
1 |
# tree |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
├── docs │ └── index.md ├── mkdocs.yml └── site ├── 404.html ├── css │ ├── base.css │ ├── bootstrap.min.css │ └── font-awesome.min.css ├── fonts │ ├── FontAwesome.otf │ ├── fontawesome-webfont.eot │ ├── fontawesome-webfont.svg │ ├── fontawesome-webfont.ttf │ ├── fontawesome-webfont.woff │ └── fontawesome-webfont.woff2 ├── img │ ├── favicon.ico │ └── grid.png ├── index.html ├── js │ ├── base.js │ ├── bootstrap.min.js │ └── jquery-1.10.2.min.js ├── search │ ├── lunr.js │ ├── main.js │ ├── search_index.json │ └── worker.js ├── sitemap.xml └── sitemap.xml.gz |
Como estou rotando em um VM de lab vou verificar qual o IP recebi por DHCP na interface e iniciar o serviço.
|
1 |
# ip -c addr |
|
1 2 3 4 |
2: enp0s3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 link/ether 08:00:27:90:63:d9 brd ff:ff:ff:ff:ff:ff inet 192.168.87.41/24 brd 192.168.87.255 scope global dynamic enp0s3 valid_lft 86031sec preferred_lft 86031sec |
Vamos iniciar o serviço de forma manual apenas para realizar um teste.
|
1 |
# mkdocs serve -a 192.168.87.41:8000 |
|
1 2 3 4 |
INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 0.05 seconds INFO - [10:41:22] Serving on http://192.168.87.41:8000/ |
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.
|
1 |
# vim /opt/mkdocs/mkdocs.yml |
|
1 2 3 4 |
site_name: My Docs theme: name: readthedocs locale: pt_BR |
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
|
1 |
# vim /etc/systemd/system/mkdocs.service |
Adicione:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
[Unit] Description=MKDocs After=network.target [Service] Type=simple User=root Group=root TimeoutStartSec=60 Restart=on-failure RestartSec=10 RemainAfterExit=yes WorkingDirectory=/opt/mkdocs ExecStart=/bin/mkdocs serve ExecReload=/bin/pkill mkdocs; /bin/mkdocs serve ExecStop=/bin/pkill mkdocs [Install] WantedBy=multi-user.target |
Recarregue daemon, em seguiga habilitamos nosso novo serviço mkdocs para inicia com o boot do sistema, e inicializamos o mesmo.
|
1 2 3 |
# systemctl daemon-reload # systemctl enable mkdocs # systemctl start mkdocs |
Verifique se o mesmo incializou
|
1 |
# systemctl status mkdocs |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
● mkdocs.service - MKDocs Loaded: loaded (/etc/systemd/system/mkdocs.service; enabled; vendor preset: enabled) Active: active (running) since Fri 2021-11-19 13:32:12 -03; 3s ago Main PID: 7160 (mkdocs) Tasks: 6 (limit: 2341) Memory: 29.8M CPU: 261ms CGroup: /system.slice/mkdocs.service └─7160 /usr/bin/python3 /bin/mkdocs serve nov 19 13:32:12 debian11 systemd[1]: Started MKDocs. nov 19 13:32:12 debian11 mkdocs[7160]: INFO - Building documentation... nov 19 13:32:12 debian11 mkdocs[7160]: INFO - Cleaning site directory nov 19 13:32:12 debian11 mkdocs[7160]: INFO - Documentation built in 0.07 seconds nov 19 13:32:12 debian11 mkdocs[7160]: INFO - [13:32:12] Serving on http://127.0.0.1:8000/ |
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!
|
1 2 3 |
# apt install nginx # sed -i 's/# server_tokens/server_tokens/' /etc/nginx/nginx.conf # mv /etc/nginx/sites-available/default /etc/nginx/sites-available/default.original |
Vou utilizar da conf default
|
1 |
# vim /etc/nginx/sites-available/default |
Adicione e altere para suas necessidades
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
server { listen 80; listen [::]:80; # Subdominios especifico #server_name mkdocs.remontti.com.br; # Todos o endereços server_name _; location / { proxy_pass http://localhost:8000; proxy_set_header Host $host; } } |
|
1 |
# systemctl restart nginx |
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:
|
1 |
# vim /opt/mkdocs/mkdocs.yml |
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.
|
1 2 3 4 5 6 7 |
site_name: Markdown Tutorial theme: name: readthedocs locale: pt_BR nav: - Home: index.md - Exemplos: exemplos.md |
Reinicie o mkdocs
|
1 |
# systemctl restart mkdocs |
Agora vamos editar/criar nossos arquivos.
# vim /opt/mkdocs/docs/index.md
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
# Markdown ## O que é Markdown ? Markdown é uma linguagem de marcação leve com sintaxe de formatação de texto simples projetada para que ela possa ser convertida em HTML e muitos outros formatos usando uma ferramenta com o mesmo nome. Markdown é usado frequentemente para formatar arquivos readme, para escrever mensagens em fóruns de discussão on-line e para criar texto rico usando um editor de texto simples. ## Porque usar Markdown? * **FÁCIL** : A sintaxe é tão fácil que você pode aprender em um minuto ou dois, em seguida, escreva sem perceber nada estranho ou nerd. * **RÁPIDO** : Ele economiza tempo em comparação com outros tipos de arquivos / formatos de texto. Isso ajuda a aumentar a produtividade e os fluxos de trabalho do escritor. * **LIMPO** : Tanto a sintaxe como a saída são limpas, sem confusão com nossos olhos e simples de gerenciar. * **FLEXÍVEL** : Com apenas algumas configurações, o seu texto será traduzido atravessando qualquer plataforma lá fora, editável em qualquer software de edição de texto e conversível para uma ampla variedade de formatos. **Em resumo**, os usuários comuns acharão útil em todos os casos, especialmente quando você precisar de algo melhor que o texto simples, mas menos funcional do que o Microsoft Word. **Para desenvolvedores**, Se você é preguiçoso para escrever código HTML, você vai adorar o markdown. **Além disso**, **Github** e muitos sites favorecem o markdown para o arquivo readme de projetos. Isso significa que você vai encontrar o markdown em sua vida de uma forma ou de outra. |
|
1 |
# vim /opt/mkdocs/docs/exemplos.md |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
# Instalação MkDocs ``` # apt install mkdocs # pip3 install mkdocs-material mkdocs[i18n] ``` Crie um novo projeto chamado mkdocs e construa um novo site ``` # cd /opt/ # mkdocs new mkdocs # cd /opt/mkdocs # mkdocs build ``` Inicie o serviço ``` # mkdocs serve -a 192.168.87.41:8000 ``` [](https://blog.remontti.com.br/doar) |
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/
