Padronização Markdown (.markdownlint)
🧭 Padronização Markdown
Este guia documenta todas as políticas definidas no arquivo .markdownlint.yml, explicando:
- Descrição de cada regra: o que faz e como funciona.
- Justificativa da configuração: por que cada regra foi adotada.
- Benefícios: ganhos de produtividade, consistência e qualidade da documentação.
- Impacto prático: efeitos diretos no fluxo editorial, revisão e manutenção dos conteúdos.
🧩 Tabela-Resumo de Políticas
| Regra | Política | Motivo | Ganho de Produtividade | Melhoria de Qualidade | Impacto |
|---|---|---|---|---|---|
| MD001 | true | Garante hierarquia coerente de H1 > H2 > H3 | +10% | Evita TOC incorreto e navegação quebrada | Reduz revisões estruturais |
| MD003 | ATX | Usa # para cabeçalhos | +5% | Uniformiza estilo e compatibilidade MDX | Evita parsing inconsistente |
| MD004 | dash | Usa - para listas não ordenadas | +3% | Mantém padrão visual | Evita formatação inconsistente |
| MD007 | indent:2 | Recuo consistente em listas | +8% | Renderização estável | Evita diffs falsos em PRs |
| MD009 | br_spaces:2 | Evita múltiplos espaços no fim da linha | +3% | Limpeza de formatação | Evita alertas em CI |
| MD012 | false | Permite linhas em branco consecutivas | +2% | Melhor legibilidade | Facilita separação visual de blocos |
| MD013 | line_length:200 | Limita comprimento de linhas | +5% | Facilita leitura e revisão | Reduz quebras artificiais |
| MD022 | lines_above:1, lines_below:1 | Uma linha acima/abaixo de títulos | +3% | Padrão visual consistente | Leitura fluida |
| MD023 | true | Evita cabeçalhos duplicados | +4% | Estrutura clara | Evita ambiguidades no TOC |
| MD025 | false | Permite múltiplos H1 (docs modulares) | +5% | Compatível com Docusaurus | Evita erro falso em README |
| MD026 | punctuation: ".,;:!?" | Controle de pontuação em títulos | +2% | Clareza e consistência | Evita inconsistência editorial |
| MD027 | true | Garante blocos de código bem fechados | +5% | Evita erro de renderização | Menos revisões manuais |
| MD029 | ordered | Numeração automática em listas ordenadas | +3% | Menos trabalho manual | Evita renumeração manual |
| MD030 | ul/ol spacing:1 | Espaçamento padronizado | +3% | Alinhamento limpo | Melhor leitura de diffs |
| MD031 | true | Linhas em branco antes/depois de código | +2% | Melhor visualização | Consistência no layout |
| MD033 | false | Permite HTML inline (MDX) | +10% | Flexibilidade em Docusaurus | Evita travas em build |
| MD034 | true | Links válidos | +5% | Evita âncoras quebradas | SEO preservado |
| MD036 | false | Permite ênfase no início de frase | +1% | Mais liberdade | Sem impacto negativo significativo |
| MD041 | false | Não exige título H1 obrigatório | +5% | Compatível com front matter | Evita redundância |
| MD042 | true | Links relativos válidos | +4% | Evita links quebrados | Navegação consistente |
| MD046 | fenced | Usa fenced | +5% | Renderização previsível | Padrão universal |
| MD048 | true | Inline code consistente | +3% | Clareza técnica | Menos ambiguidade |
| MD049 | consistent | Itálico consistente | +2% | Uniformidade | Evita ruído visual |
| MD050 | consistent | Negrito consistente | +2% | Uniformidade | Evita ruído visual |
| MD052 | false | Permite títulos duplicados | +1% | Flexibilidade | Baixo impacto |
| MD055 | true | IDs de cabeçalhos consistentes | +8% | Links automáticos confiáveis | Evita falhas no TOC |
| MD056 | true | URLs absolutas completas | +4% | Links rastreáveis | Evita redirecionamentos |
| MD057 | true | Evita múltiplos espaços entre palavras | +3% | Texto limpo | Diminui ruído em diffs |
📝 Explicações Detalhadas das Políticas
MD001 – Hierarquia coerente de cabeçalhos (H1 > H2 > H3)
Motivo: Garante que a estrutura da documentação siga a ordem correta de hierarquia.
Impacto: Evita erros de TOC e facilita navegação.
Produtividade: Reduz revisões estruturais e confusões durante escrita colaborativa.
MD003 – Cabeçalhos ATX (#)
Motivo: Mantém consistência visual e compatibilidade com Docusaurus e MDX.
Impacto: Evita parsing inconsistente.
Produtividade: Padroniza escrita e evita revisões manuais de estilo.
MD004 – Listas não ordenadas com -
Motivo: Uniformiza listas para melhor legibilidade e diffs claros.
Impacto: Evita inconsistências visuais.
Produtividade: Facilita revisão e colaboração.
MD007 – Recuo consistente em listas
Motivo: Garante alinhamento correto de itens aninhados.
Impacto: Evita erros de renderização.
Produtividade: Diminui retrabalho em PRs.
MD009 – Espaços no fim da linha
Motivo: Remove espaços redundantes.
Impacto: Código e texto mais limpos.
Produtividade: Evita alertas automáticos em CI.
MD012 – Linhas em branco consecutivas
Motivo: Permite maior legibilidade em blocos de texto longos.
Impacto: Documentação visualmente mais clara.
Produtividade: Facilita leitura e revisão.
MD013 – Limite de comprimento de linha
Motivo: Mantém linhas dentro de limites de leitura confortável.
Impacto: Evita quebras inesperadas em renderização.
Produtividade: Menos ajustes manuais.
MD022 – Linhas acima/abaixo de títulos
Motivo: Padroniza espaçamento antes e depois de títulos.
Impacto: Visual consistente, leitura fluida.
Produtividade: Menos necessidade de ajustes estéticos.
MD023 – Evita cabeçalhos duplicados
Motivo: Garante unicidade dos títulos.
Impacto: Evita ambiguidades no TOC.
Produtividade: Facilita navegação e manutenção.
MD025 – Permite múltiplos H1
Motivo: Necessário para documentação modular em Docusaurus.
Impacto: Evita erro falso em README.
Produtividade: Flexível sem quebrar builds.
MD026 – Pontuação em títulos
Motivo: Controla sinais de pontuação em títulos.
Impacto: Melhora clareza e estilo.
Produtividade: Evita inconsistência editorial.
MD027 – Blocos de código bem fechados
Motivo: Garante renderização correta de blocos de código.
Impacto: Evita erros visuais.
Produtividade: Menos revisões manuais.
MD029 – Numeração automática
Motivo: Listas ordenadas são numeradas automaticamente.
Impacto: Evita renumeração manual.
Produtividade: Acelera criação de listas.
MD030 – Espaçamento padronizado
Motivo: Mantém espaçamento uniforme em listas.
Impacto: Diferenças visuais mínimas.
Produtividade: Facilita leitura de diffs.
MD031 – Linhas em branco em blocos de código
Motivo: Melhora visualização de blocos de código.
Impacto: Layout consistente.
Produtividade: Mais legível e padronizado.
MD033 – Permite HTML inline
Motivo: Necessário para integrações MDX.
Impacto: Evita travas no build.
Produtividade: Permite flexibilidade editorial.
MD034 – Links válidos
Motivo: Garante URLs corretas.
Impacto: SEO preservado, navegação confiável.
Produtividade: Evita correções de links quebrados.
MD036 – Permite ênfase no início
Motivo: Mais liberdade de estilo.
Impacto: Baixo impacto.
Produtividade: Flexibilidade na escrita.
MD041 – H1 opcional
Motivo: Docusaurus usa front matter, não obrigando H1.
Impacto: Evita redundância.
Produtividade: Menos ajustes manuais.
MD042 – Links relativos válidos
Motivo: Confere validade de links locais.
Impacto: Navegação consistente.
Produtividade: Reduz erros de hyperlink.
MD046 – Blocos de código cercados
Motivo: Uso de fenced garante renderização universal.
Impacto: Evita inconsistências em diferentes renderizadores.
Produtividade: Menos problemas em CI/CD.
MD048 – Inline code consistente
Motivo: Padroniza uso de código inline.
Impacto: Clareza técnica.
Produtividade: Menos ambiguidades.
MD049/050 – Itálico e negrito consistentes
Motivo: Uniformiza estilo textual.
Impacto: Evita ruído visual.
Produtividade: Menos revisões estilísticas.
MD052 – Permite títulos duplicados
Motivo: Flexibilidade em seções semelhantes.
Impacto: Baixo.
Produtividade: Pequeno ganho em documentação modular.
MD055 – IDs de cabeçalhos consistentes
Motivo: Permite links automáticos confiáveis.
Impacto: TOC consistente e navegação segura.
Produtividade: Evita correções manuais.
MD056 – URLs absolutas completas
Motivo: Links rastreáveis e SEO-friendly.
Impacto: Evita redirecionamentos.
Produtividade: Mais confiabilidade em links.
MD057 – Evita múltiplos espaços
Motivo: Limpeza de texto e consistência.
Impacto: Diminui ruído em diffs.
Produtividade: Menos correções manuais.
Fonte: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
📊 Estimativas de Ganho Global
| Tipo de ganho | Estimativa média | Observação |
|---|---|---|
| Produtividade editorial | +45 – 55% | Menos tempo gasto com ajustes manuais |
| Erros editoriais evitados | 80 – 90% | Renderização, links, hierarquia e pontuação |
| Compatibilidade técnica | 100% | Totalmente compatível com Docusaurus e CI/CD |
| Tempo economizado por PR e edição no geral (~1k linhas) | 30 – 45 min | Revisões automatizadas e consistentes |
🎯 Conclusão
Utizar o .markdownlint.yml para projetos com base em arquivo .md é uma ferramenta essencial, para evitar perda produtiva.
Utilze ele de forma automatica como por exemplo:
"lint:md": "markdownlint-cli2 '**/*.md' --config .markdownlint.yml",
"lint:md:fix": "markdownlint-cli2 --fix '**/*.md' --config .markdownlint.yml",
"format:all": "prettier --write '**/*.{js,jsx,ts,tsx,md,mdx,json,yml,yaml}' && npm run lint:md:fix"