Skip to content

📖 Como Esconder e Exibir Conteúdos no MkDocs

No MkDocs, podemos esconder e exibir conteúdos usando blocos expansíveis. Isso ajuda a manter a documentação mais limpa e organizada, permitindo que o usuário expanda apenas as informações que deseja visualizar.

✅ Criando um Bloco Expansível

Para criar um bloco de conteúdo escondido, use o seguinte formato:

??? note "Título do bloco expansível"

    Aqui vai o conteúdo que ficará oculto até que o usuário clique para expandir.

    ```bash
    # Exemplo de código Bash
    echo "Este código só aparece quando o bloco for expandido!"
    ```

🔹 Explicação:

  • ??? note "Título" → Cria um bloco expansível com o título definido.
  • Linha em branco após ??? note → Necessário para que o bloco funcione corretamente.
  • Indentação com 4 espaços → O conteúdo dentro do bloco deve estar indentado.

📌 Configuração do mkdocs.yml

Para que os blocos expansíveis funcionem corretamente, o arquivo mkdocs.yml precisa conter as extensões adequadas:

markdown_extensions:
  - pymdownx.details
  - pymdownx.superfences

Isso garante que os blocos ??? sejam renderizados corretamente.

🎨 Outros Tipos de Blocos Expansíveis

O MkDocs permite diferentes estilos para os blocos expansíveis, dependendo da finalidade:

Tipo Código Exemplo
Nota ??? note "Título" 📝 Para informações adicionais.
Dica ??? tip "Título" 💡 Para sugestões ou dicas.
Aviso ??? warning "Título" ⚠️ Para alertas importantes.
Erro ??? danger "Título" ❌ Para erros críticos.

Exemplo de um bloco de dica:

??? tip "Dica útil"

    Você pode usar esse recurso para esconder comandos longos e deixar sua documentação mais organizada! 🚀

📌 Criando Tabelas no MkDocs

Tabelas são úteis para documentar configurações de rede, VLANs e parâmetros técnicos:

| Configuração | Valor  | Descrição                  |
|-------------|--------|----------------------------|
| IP Gateway  | 192.168.1.1 | Endereço do roteador   |
| Máscara     | 255.255.255.0 | Máscara de sub-rede |
| DNS Primário | 8.8.8.8 | Servidor DNS do Google   |

📌 Criando Alternativas às Abas no MkDocs Swan

O tema Swan não suporta abas nativamente, então podemos usar blocos expansíveis para simular o mesmo efeito:

??? note "MikroTik"
    ```bash
    /ip address add address=192.168.1.1/24 interface=ether1
    ```

??? note "Cisco"
    ```bash
    interface GigabitEthernet0/1
    ip address 192.168.1.1 255.255.255.0
    ```

Isso permite organizar conteúdos sem ocupar muito espaço na tela.

📌 Criando Avisos Importantes

Se quiser destacar comandos críticos ou procedimentos arriscados, pode usar admonitions:

!!! danger "Atenção!"
    **Alterar essa configuração pode derrubar sua rede.**  
    Tenha certeza antes de aplicar os comandos!

📌 Criando Listas de Tarefas Interativas

Para guias passo a passo, use checklists interativos:

- [x] Configurar IP estático  
- [ ] Criar firewall rules  
- [ ] Habilitar NAT  
- [ ] Configurar VLANs

Isso ajuda os usuários a acompanharem o progresso na configuração.

Explicar como criar links internos dentro do MkDocs melhora a navegação:

[Ir para a seção de Dicas](#🎨-outros-tipos-de-blocos-expansíveis)

Isso facilita para os usuários encontrarem rapidamente as seções importantes dentro da documentação.

🛠️ Testando no MkDocs

  1. Crie um arquivo Markdown (.md) e adicione os blocos expansíveis conforme mostrado nos exemplos.
  2. Inicie o servidor local para visualizar a documentação: 
    mkdocs serve
  3. Abra o navegador e acesse http://127.0.0.1:8000 para ver os blocos expansíveis funcionando!

Agora sua documentação pode ficar mais organizada e interativa! 🚀

Comando Descrição
ip a Lista os endereços IP
systemctl restart serviço Reinicia um serviço no Linux

❓ Perguntas Frequentes (FAQ)

Por que meu MkDocs não está carregando?

Certifique-se de que você rodou mkdocs serve e que não há erros no terminal.

Como faço para adicionar abas no tema Swan?

O tema Swan não suporta abas, mas você pode usar blocos expansíveis com ??? note como alternativa.

```mermaid graph TD; Inicio -->|Configurar IP| Roteador; Roteador -->|Habilitar NAT| Internet; Internet -->|Teste de Conexão| Cliente;

⚠️ Problema detectado:
No seu Markdown, o código Mermaid aparece sem a marcação de código correta (```mermaid). Isso faz com que ele seja tratado como texto normal.

📌 Solução:
- Certifique-se de que o Mermaid está ativado no mkdocs.yml:

```yaml markdown_extensions: - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid

🖧 Comandos para Configuração de Redes

Equipamento Comando para Configurar IP
MikroTik /ip address add address=192.168.1.1/24 interface=ether1
Cisco interface GigabitEthernet0/1 \n ip address 192.168.1.1 255.255.255.0
Linux ip addr add 192.168.1.1/24 dev eth0

!!! warning "Cuidado com essa configuração!" Isso pode impactar o funcionamento da sua rede.

!!! success "Configuração aplicada com sucesso!" Agora seu serviço está rodando corretamente.

!!! info "Dica útil" Se precisar de mais ajuda, consulte a documentação oficial.

✅ Passos para Configuração

  • Configurar IP estático
  • Criar regras de firewall
  • Habilitar NAT
  • Configurar VLANs