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
```
[![Doação](https://blog.remontti.com.br/wp-content/uploads/2019/07/quero-doar-remontti.png)](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/

O post Como Instalar MkDocs No Debian 11 apareceu primeiro em Remontti.