🗺️ A Esteira de Garantia de Qualidade de Documentação (Docs Quality Gate)

flowchart LR
    DEV["Desenvolvedor Escreve Documentação .md"]
    --> HOOK["Git Pre-commit Hook (Husky / Lefthook)"]

    HOOK --> LINT["markdownlint-cli (Valida regras estruturais: MD001, MD009, MD025)"]
    HOOK --> FORMAT["Prettier (Formata tabelas, quebras de linha e indentação)"]

    LINT & FORMAT --> CHECK{"Regras Aprovadas?"}
    CHECK -- "NÃO" --> REJECT["Commit Rejeitado com Alertas Objetivos de Correção 🚨"]
    CHECK -- "SIM" --> COMMIT["Commit Concluído com Documentação 100% Padronizada ⚡"]

    style DEV fill:#ede7f6,stroke:#512da8,stroke-width:2px
    style HOOK fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    style LINT fill:#e1f5fe,stroke:#03a9f4,stroke-width:1.5px
    style FORMAT fill:#e8f5e9,stroke:#4caf50,stroke-width:1.5px
    style CHECK fill:#fff9c4,stroke:#fbc02d,stroke-width:2px
    style REJECT fill:#ffebee,stroke:#d32f2f,stroke-width:1.5px
    style COMMIT fill:#00897b,stroke:#004d40,stroke-width:2px,color:#ffffff

📖 Fundamentos e Aplicação

No paradigma Docs-as-Code, documentação é tratada com o mesmo rigor de engenharia de software aplicado ao código de produção. Permitir espaços em branco soltos no final de linhas, saltos ilegais de cabeçalhos e tabelas desalinhadas prejudica o versionamento Git (gerando diffs ruidosos) e quebra renderizadores.

1. markdownlint: O Guardião de Regras Estruturais

O markdownlint aplica mais de 50 regras canônicas de consistência:

  • MD001 / heading-increment: Níveis de cabeçalhos devem ser incrementados de um em um.
  • MD009 / no-trailing-spaces: Proíbe espaços invisíveis no final de linhas.
  • MD013 / line-length: Controla o comprimento máximo de linhas (ex: limite de 120 caracteres).
  • MD025 / single-title: Deve haver exatamente um único título H1 no topo do documento.

2. Prettier: Formatação Automática Determinística

O Prettier alinha tabelas Markdown automaticamente, normaliza blocos de código e ajusta a indentação de listas com um único comando: npx prettier --write "**/*.md".