Markdown é permissivo.Um documento com erros estruturais ainda pode ser renderizado, o que torna esses erros fáceis de perder até que uma tabela seja quebrada, um título desapareça da navegação ou uma imagem perca o sentido para um usuário de leitor de tela.
Markdown linting é o processo de verificação do texto fonte em busca de problemas estruturais, de acessibilidade e de consistência antes da publicação.Comece com o Linter de Markdown para capturar níveis de cabeçalho ignorados, texto alternativo de imagem ausente, URLs vazios, limites de código não rotulados ou não fechados e espaços em branco à direita.Em seguida, use a lista de verificação manual deste guia para uma revisão editorial mais ampla.
Linting não se trata de impor preferências arbitrárias.Uma regra útil deve evitar problemas reais de leitura, renderização, manutenção ou acessibilidade.
Lista de verificação rápida de pré-publicação
| Verificação | Por que é importante | Automatizado ou manual? |
|---|---|---|
| Hierarquia de títulos | Preserva a estrutura do documento | Linter |
| Texto alternativo da imagem | Torna as imagens compreensíveis sem visão | Linter |
| Links descritivos | Melhora a acessibilidade e a digitalização | Linter + revisão manual |
| Cercas de código fechado | Evita que o restante da página se transforme em código | Linter |
| Rótulos de linguagem de código | Permite realce de sintaxe útil | Linter |
| Espaço em branco à direita | Evita comportamento invisível e específico do dialeto | Linter |
| Um título de página claro | Mantém o propósito da página inequívoco | Revisão manual |
| Listas consistentes | Evita aninhamento quebrado | Revisão manual |
| Tabelas válidas | Mantém a estrutura da coluna intacta | Revisão manual |
| Títulos exclusivos | Evita confusão de âncoras duplicadas | Revisão manual |
| Uso portátil HTML | Evita falhas específicas do renderizador | Revisão manual |
| Parágrafos legíveis | Melhora a compreensão | Revisão manual |
Cole um documento representativo no linter, execute as verificações, corrija as linhas relatadas e, em seguida, visualize a página completa em seu sistema de publicação real.
1. Níveis de título ignorados
Problema
# Deployment Guide
### Configure credentials
O documento salta de H1 para H3.Pode parecer aceitável quando os tamanhos das fontes são o único sinal visível, mas falta um nível no contorno estrutural.
Correção
# Deployment Guide
## Configure credentials
Use títulos para descrever hierarquia, não para escolher um tamanho visual.Se “Configurar credenciais” realmente pertencer a uma seção ausente, adicione essa seção:
# Deployment Guide
## Preparation
### Configure credentials
O Linter de Markdown relata um rumo que salta mais de um nível.
2. Títulos H1 múltiplos ou ausentes
Uma página normalmente deve ter um título claro.Alguns sistemas de documentação geram o H1 a partir do assunto inicial, enquanto outros o esperam no corpo Markdown.Saiba qual convenção seu site usa.
Fonte ambígua
# Installation
# Configuration
Limpar fonte
# Product setup
## Installation
## Configuration
Se o modelo do seu site for renderizado title: Product setup como página H1, o corpo pode começar com H2.A regra não é “cada arquivo Markdown deve conter exatamente um #.” The rule is “the rendered page needs one unambiguous primary heading.”
3. Títulos usados apenas para ênfase
Esta fonte cria uma entrada de contorno desnecessária:
#### Important!
Se o texto não introduzir uma seção, use prosa ou texto explicativo apropriado:
**Important:** Back up the database before continuing.
Os títulos devem ajudar os leitores a navegar.Os títulos decorativos tornam o índice barulhento e reduzem a utilidade da navegação assistida.
4. Imagens sem texto alternativo
Problema

A imagem não possui alternativa de texto.Um leitor que não consegue vê-lo não recebe nenhuma explicação, e alguém que navega em imagens quebradas ou desativadas não consegue determinar seu propósito.
Correção

Descreva as informações que a imagem contribui, não apenas sua aparência.Evite frases como “imagem de”, a menos que o meio seja importante.
As imagens decorativas são um caso especial.O texto alternativo vazio pode ser correto em HTML quando uma imagem não transmite nenhuma informação, mas os renderizadores e fluxos de trabalho de conteúdo Markdown são diferentes.Se uma imagem for puramente decorativa, pergunte primeiro se ela pertence à documentação técnica.
O linter sinaliza imagens Markdown com texto alternativo vazio.O Formatador de imagens pode gerar marcação de imagem com uma alternativa explícita e legenda opcional.
5. Links fracos ou nus
Problema
Visit https://example.com/docs/setup for more information.
URLs simples são difíceis de digitalizar e podem ser desagradáveis quando lidos em voz alta.O texto do link genérico não é muito melhor:
[Click here](https://example.com/docs/setup).
Correção
Read the [service setup guide](https://example.com/docs/setup).
Links descritivos informam aos leitores o que eles abrirão.Eles também permanecem significativos quando extraídos para uma lista de links.
O linter identifica muitos http:// and https:// URLs, mas a revisão editorial ainda é necessária para julgar se o texto do link é útil.
6. Cercas de código não fechadas
Problema
```javascript
const status = 'ready';
## Next section
Sem uma barreira de fechamento, o renderizador pode tratar o resto da página como código.
Correção
```javascript
const status = 'ready';
```
## Next section
Uma cerca aberta pode quebrar uma grande parte de um documento válido.O linter informa a linha onde começa a cerca sem correspondência.
7. Limites de código sem identificadores de idioma
Menos útil
```
npm run build
```
Melhor
```bash
npm run build
```
Um identificador de idioma permite o destaque de sintaxe e comunica que tipo de conteúdo o leitor está vendo.Use identificadores comuns, como javascript, typescript, json, html, css, bash, powershell, yamlou markdown.
Não adicione uma linguagem imprecisa apenas para obter cores.Para saída não estruturada, use text quando o destino o reconhece.
8. Recuo de lista inconsistente
Problema
- Install dependencies
- Production packages
* Development packages
- Optional tools
Tabulações, espaços e marcadores mistos são difíceis de revisar e podem ser renderizados em diferentes níveis.
Correção
- Install dependencies
- Production packages
- Development packages
- Optional tools
Escolha uma largura de recuo consistente para o projeto.O número exato de espaços pode depender do dialeto Markdown e do conteúdo da lista, mas a consistência é essencial.
Utilize o Formatador de listas aninhadas para normalizar marcadores, numeração, tabulações e recuos mistos antes da revisão final.
9. Sequências numéricas digitadas manualmente
Listas numeradas longas são caras de manter:
1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.
Muitos renderizadores Markdown permitem que cada item seja usado 1. enquanto ainda exibe uma sequência ordenada:
1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.
Isso reduz o ruído de renumeração nas diferenças de fonte.No entanto, a fonte explicitamente numerada é mais fácil de discutir quando as instruções se referem ao “passo 3”.Escolha uma convenção de projeto e aplique-a de forma consistente.
Não combine números digitados, marcadores de lista ordenada e texto de parágrafo.Confirme o resultado renderizado após editar as etapas aninhadas.
10. Tabelas malformadas
Problema
| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |
O separador e as linhas de dados não contêm o mesmo número lógico de colunas.
Correção
| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |
Verifique também se há caracteres verticais sem escape dentro das células:
| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |
O Formatador de tabelas Markdown ajuda a expor linhas irregulares e produz fontes alinhadas.Para criar uma nova tabela visualmente, use o Markdown Gerador de tabelas.
11. Rumos duplicados e colisões de âncora
Um documento pode repetir legitimamente um título visível como “Exemplos”, mas os IDs de âncora gerados automaticamente podem se tornar #examples, #examples-1e #examples-2.A regra exata varia de acordo com o renderizador.
Títulos repetidos tornam os links manuais frágeis:
- [API examples](#examples)
- [CLI examples](#examples)
Prefira títulos descritivos:
## API examples
## CLI examples
Em seguida, gere um índice com o Markdown Gerador de TOC e verifique as âncoras na plataforma alvo.
12. Espaço em branco final
Os espaços no final de uma linha são invisíveis.Em alguns dialetos Markdown, dois espaços à direita criam uma quebra de linha rígida, o que significa que uma ação acidental do editor pode alterar a renderização.
O linter relata espaços em branco à direita para que você possa decidir se é deliberado.Prefira uma linha vazia para separação de parágrafos.Se uma quebra de linha dura for genuinamente necessária, documente e aplique a convenção escolhida para o projeto de forma consistente.
Os editores geralmente podem remover os espaços em branco automaticamente ao salvar, mas verifique se isso não altera as quebras de linha intencionais no conteúdo legado.
13. Raw HTML que reduz a portabilidade
Markdown geralmente permite HTML incorporado:
<div class="warning-panel">
Restarting the service ends active sessions.
</div>
Esse bloco pode funcionar em um site e ser escapado, higienizado ou estilizado incorretamente em outro lugar.Prefira portátil Markdown quando puder expressar o mesmo significado:
> **Warning:** Restarting the service ends active sessions.
Use HTML deliberadamente para recursos que Markdown não podem ser expressos, como tamanho de imagem controlado ou um tamanho suportado <details> .Mantenha uma lista dos destinos onde o conteúdo deve ser renderizado e teste cada um deles.
O Gerador de chamada pode produzir sintaxe específica de plataforma para GitHub, Obsidian e MkDocs quando a portabilidade é menos importante que a apresentação nativa.
14. Parágrafos muito longos e escaneabilidade deficiente
Markdown pode ser estruturalmente válido e ainda assim difícil de ler.Uma parede de texto contendo diversas decisões, advertências e procedimentos deve ser reorganizada.
Uso:
- parágrafos curtos para uma ideia principal;
- títulos descritivos para navegação;
- listas para itens paralelos;
- tabelas para campos genuinamente comparáveis;
- blocos de código para entrada e saída literal;
- textos explicativos para um pequeno número de exceções importantes.
Não transforme cada frase em um marcador.As listas funcionam melhor quando os itens têm a mesma função gramatical e conceitual.
Utilização Contagem de palavras e tempo de leitura para inspecionar a contagem de parágrafos, a contagem de títulos e o comprimento da leitura, mas tratar as estatísticas como sinais em vez de alvos.
15. Sintaxe específica do renderizador sem um plano de compatibilidade
GitHub listas de tarefas, Obsidian links wiki, MkDocs advertências, notas de rodapé, listas de definições e assuntos iniciais são todos úteis, mas não são suportados de forma idêntica em todos os lugares.
Por exemplo:
> [!NOTE]
> This callout is useful in destinations that recognize the syntax.
Antes de adotar uma extensão, responda três perguntas:
- Qual renderizador possui a saída final?
- O conteúdo precisa ser movido para outro lugar posteriormente?
- O que os leitores verão quando a extensão não for suportada?
Mantenha uma base portátil Markdown e adicione sintaxe de plataforma na borda de publicação quando possível.
Um fluxo de trabalho prático de linting
Passo 1: Verifique a estrutura
Cole a fonte no Linter de Markdown.Corrija primeiro os erros, depois os avisos e depois os itens de consistência informacional.As verificações automatizadas devem identificar os locais;eles não deveriam reescrever silenciosamente o significado.
Etapa 2: Normalizar elementos difíceis
Use ferramentas específicas para limpeza mecânica:
- Formatador de listas aninhadas para recuo;
- Formatador de tabelas Markdown para tabelas de tubos;
- Formatador de imagens para marcação de imagem;
- Gerador de sumário para âncoras de proa.
Alterações focadas produzem diferenças menores e mais fáceis de revisar do que um formatador amplo que reescreve o arquivo inteiro.
Etapa 3: visualizar o documento
Abra o código-fonte no Markdown Editor e compare Markdown com a saída renderizada.Verifique:
- títulos e índice;
- listas e listas de tarefas;
- tabelas em tela estreita;
- imagens e links;
- blocos de código e código inline;
- textos explicativos ou HTML bruto.
Etapa 4: Teste o destino real
Uma visualização genérica não pode reproduzir todos os renderizadores.Abra o arquivo em GitHub, Obsidian, GitLab, MkDocs ou no próprio site de documentação antes de publicar.
Etapa 5: Revise o significado, não apenas a sintaxe
Nenhum linter pode determinar se um procedimento é seguro, um link aponta para a política pretendida ou uma descrição de imagem comunica a conclusão importante.Um revisor humano deve confirmar a precisão, integridade, tom e adequação ao público.
Recomendações do Guia de Estilo da Equipe
Uma convenção curta e documentada é mais eficaz do que dezenas de preferências tácitas.Definir:
- se o título da página está no cabeçalho ou no corpo Markdown;
- a progressão de rumo permitida;
- recuo de lista e estilo de lista ordenada;
- requisitos de linguagem de delimitação de código;
- como as imagens e o texto alternativo são revisados;
- limites de complexidade da tabela;
- permitido HTML e extensões de plataforma;
- comprimento máximo da linha, caso a equipe utilize;
- como os links são verificados;
- quais regras do linter bloqueiam a publicação.
Comece com regras que evitem defeitos reais.Adicione uma regra somente quando a equipe entender o problema que ela resolve.
FAQ
O Markdown válido é acessível automaticamente?
Não. A sintaxe válida ainda pode conter texto alternativo vazio, links vagos, títulos confusos, diagramas inacessíveis e má ordem de leitura.A acessibilidade requer revisão estrutural e editorial.
O Markdown Linter reescreverá meu documento?
O linter WordToMD relata problemas com números de linha.Ele não reescreve silenciosamente a fonte, portanto você mantém o controle sobre cada correção.
Por que o linter reporta uma URL simples?
O texto do link descritivo é mais fácil de digitalizar e mais útil para tecnologia assistiva.Substitua o URL por um rótulo significativo, a menos que o endereço literal seja a informação de que os leitores precisam.
Uma barreira de código sem rótulo é sempre errada?
Nem sempre, mas um identificador de idioma correto geralmente melhora a clareza e o realce da sintaxe.Usar text para saída simples quando compatível, em vez de atribuir uma linguagem de programação imprecisa.
Todos os projetos deveriam usar as mesmas regras de linting?
Não. Um GitHub README, um cofre Obsidian, uma referência API e um site de publicação têm convenções diferentes.Compartilhe um conjunto básico de regras estruturais e de acessibilidade e, em seguida, adicione verificações específicas do destino.
O linting pode substituir a revisão?
Não. Um linter detecta padrões.Ele não pode verificar com segurança a verdade técnica, a qualidade do argumento, a intenção do usuário ou se uma frase é compreensível no contexto.
Conclusão
Bom Markdown é mais do que fonte que renderiza.Possui um esboço claro, links significativos, imagens acessíveis, limites de código completos, listas consistentes, tabelas válidas e um relacionamento definido com sua plataforma de publicação.
Execute o Linter de Markdown para verificações estruturais rápidas, use o Markdown Editor para revisão visual e aplique formatadores focados apenas onde eles tornam a fonte mais fácil de manter.O resultado é Markdown que é mais portátil, acessível e confiável em edições futuras.