Padrões de Escrita e Formatação¶

Para garantir clareza, consistência visual e leitura agradável, adote as seguintes práticas ao redigir documentos.

1. Títulos e Subtítulos¶

Use apenas um # Título Principal (H1) por página.
Utilize ## Subtítulo (H2) e ### Tópico (H3) para seções e subseções.

2. Caixas de Destaque (Admonitions)¶

O tema Material for MkDocs suporta caixas de destaque contextuais:

Nota

Informações complementares ou contexto importante.

Dica

Sugestões de produtividade, atalhos ou boas práticas.

Atenção

Pontos de atenção para evitar falhas ou comportamentos indesejados.

Perigo

Avisos críticos que podem causar indisponibilidade ou perda de dados.

3. Blocos de Código¶

Sempre especifique a linguagem do bloco de código para que o realce de sintaxe seja aplicado:

# Exemplo de comando bash
echo "Documentando processos com MkDocs"

# Exemplo em Python
def saudacao(nome: str) -> str:
    return f"Olá, {nome}!"

4. Diagramas Mermaid¶

Diagramas são suportados nativamente sem necessidade de exportar imagens:

sequenceDiagram
    autonumber
    Usuário->>GitHub: Envia Commit / Abre PR
    GitHub->>GitHub Actions: Dispara Pipeline de CI/CD
    GitHub Actions->>Firebase Hosting: Realiza Build do MkDocs e Deploy
    Firebase Hosting-->>Usuário: Documentação Atualizada e Publicada!