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
# apt install wget net-tools tree python3-pip vim
Instalação MkDocs
# apt install mkdocs # pip3 install mkdocs-material mkdocs[i18n]
Verificando a versão instalada
# mkdocs --version
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
# cd /opt/ # mkdocs new mkdocs # cd /opt/mkdocs # mkdocs build
Verifique se os seguintes arquivos foram criados com sucesso
# tree
├── 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.
# ip -c addr
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.
# mkdocs serve -a 192.168.87.41:8000
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.
# vim /opt/mkdocs/mkdocs.yml
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
# vim /etc/systemd/system/mkdocs.service
Adicione:
[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.
# systemctl daemon-reload # systemctl enable mkdocs # systemctl start mkdocs
Verifique se o mesmo incializou
# systemctl status mkdocs
● 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!
# 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
# vim /etc/nginx/sites-available/default
Adicione e altere para suas necessidades
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;
}
}
# 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:
# 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.
site_name: Markdown Tutorial
theme:
name: readthedocs
locale: pt_BR
nav:
- Home: index.md
- Exemplos: exemplos.md
Reinicie o mkdocs
# systemctl restart mkdocs
Agora vamos editar/criar nossos arquivos.
# vim /opt/mkdocs/docs/index.md
# 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.
# vim /opt/mkdocs/docs/exemplos.md
# 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/
