Markdown é uma linguagem de marcação leve que permite escrever texto formatado usando apenas caracteres simples do teclado. Em vez de clicar em botões de negrito ou inserir tags HTML, você escreve, por exemplo, dois asteriscos em volta de uma palavra para deixá-la em negrito. O texto permanece legível mesmo sem ser renderizado, e ferramentas convertem essa marcação em HTML. Neste guia você entende onde o Markdown é usado, a sintaxe básica, os erros comuns e quando vale visualizar a prévia. Para escrever e ver o resultado, use o Markdown preview, que renderiza localmente no navegador.
Resposta rápida
- Markdown é uma marcação leve:
#para título,**para negrito,-para lista. - É convertido em HTML e usado em README, docs, GitHub, blogs e notas.
- Não há padrão único: CommonMark padroniza o básico e o GFM adiciona tabelas e listas de tarefas.
- A prévia ajuda a conferir tabelas e listas; prefira uma que não envie o conteúdo a servidor.
O que é Markdown
Criado para ser fácil de ler e de escrever, o Markdown nasceu da ideia de que um texto formatado deveria continuar legível em sua forma bruta. Por ser texto puro, ele combina bem com controle de versão: um diff de Markdown mostra claramente o que mudou, ao contrário de formatos binários. Essa simplicidade explica por que ele virou padrão em documentação e em plataformas de desenvolvimento.
Onde o Markdown é usado
- README: a página inicial de praticamente todo repositório.
- GitHub e GitLab: issues, pull requests e wikis.
- Documentação: sites estáticos e geradores de docs.
- Blogs: muitos CMS e geradores estáticos aceitam Markdown.
- Notas: ferramentas como Obsidian e Notion.
Sintaxe básica
Os elementos mais usados são poucos e fáceis de lembrar:
| Elemento | Marcação |
|---|---|
| Título | # Título / ## Subtítulo |
| Negrito / itálico | **negrito** / *itálico* |
| Lista | - item (ou 1. item) |
| Link | [texto](url) |
| Código inline | `código` |
| Citação | > citação |
# Título nível 1
## Título nível 2
Texto com **negrito**, *itálico* e `código inline`.
- item de lista
- outro item
1. lista ordenada
2. segundo item
[texto do link](https://valorfinal.com.br)
> citação
| Nome | Idade |
| ----- | ----- |
| Maria | 30 |
```js
const x = 1;
```Esses blocos cobrem a maior parte da escrita técnica: títulos para estrutura, listas para enumerar, links para referência, citações para destacar e blocos de código para exemplos.
Diferença entre Markdown e HTML
O HTML é a linguagem que o navegador realmente entende, com tags para cada elemento. O Markdown é um atalho legível que é convertido em HTML. Para a maioria dos textos, o Markdown é mais rápido de escrever e mais fácil de ler na origem. Quando você precisa de algo que o Markdown não cobre, muitos renderizadores aceitam HTML embutido. Por segurança, porém, visualizadores cuidadosos tratam HTML colado como texto, para não executar scripts maliciosos dentro de um documento. O Markdown preview do ValorFinal segue essa abordagem segura: ele converte a marcação em elementos, sem renderizar HTML bruto.
Erros comuns
- Esquecer a linha em branco antes de uma lista ou de um título.
- Misturar marcadores de lista diferentes no mesmo bloco.
- Não fechar os três acentos graves de um bloco de código.
- Usar tabela em um renderizador que não suporta GFM.
- Esperar que todo Markdown renderize igual em todas as ferramentas.
Quando usar a prévia
A prévia é especialmente útil para conferir tabelas, listas aninhadas e blocos de código antes de publicar. Editar com a prévia ao lado evita surpresas, como um título que não virou título por falta de espaço depois do sinal de número. Uma prévia local, que não envia o conteúdo para servidor, deixa você revisar documentos internos com tranquilidade.
Exemplo completo
Um trecho de README costuma combinar título, parágrafo, lista e bloco de código, exatamente como no exemplo de sintaxe acima. Ao colá-lo em um visualizador, o resultado é uma página formatada, com hierarquia clara e código destacado, pronta para publicar no repositório. Para comparar duas versões de um documento Markdown, o comparador de texto mostra o que mudou entre elas.
CommonMark, GFM e por que o resultado varia
Uma dúvida frequente é por que o mesmo texto Markdown renderiza diferente em ferramentas distintas. A razão é histórica: o Markdown original deixou muitos detalhes em aberto, e cada projeto implementou do seu jeito. O CommonMark surgiu para padronizar o comportamento básico, definindo com precisão como títulos, listas e ênfase devem ser interpretados. Já o GitHub Flavored Markdown (GFM) é uma extensão do CommonMark que adiciona tabelas, listas de tarefas com caixas de seleção, riscado e detecção automática de links.
Na prática, isso significa que recursos como tabelas podem funcionar em uma ferramenta e não em outra mais antiga. Antes de depender de um recurso, verifique se o destino suporta GFM. Para conteúdo que vai para o GitHub ou GitLab, você pode contar com tabelas e listas de tarefas; para um renderizador genérico e antigo, fique no subconjunto básico de títulos, listas, ênfase, links e código.
Boas práticas de escrita ajudam a evitar surpresas: deixe uma linha em branco separando blocos diferentes, seja consistente no marcador de lista, e use blocos de código cercados por três acentos graves em vez de indentação, que é mais frágil. Markdown bem escrito é fácil de ler na origem e renderiza de forma previsível, que é justamente o propósito do formato.
Markdown e segurança ao renderizar
Quando uma aplicação aceita Markdown de usuários, surge uma preocupação de segurança. Como muitos renderizadores permitem HTML embutido, um texto malicioso poderia incluir um script e tentar executá-lo no navegador de quem visualiza. Por isso, sistemas que recebem Markdown de terceiros sanitizam o resultado, removendo tags perigosas, ou convertem a marcação em elementos seguros sem permitir HTML bruto. É o mesmo princípio de não confiar em conteúdo externo sem tratamento.
Para o usuário comum que só escreve seus próprios documentos, o risco é baixo, mas a recomendação prática é preferir ferramentas de prévia que não renderizam HTML bruto e que processam tudo localmente. Assim, além de seguro, o conteúdo do seu documento não é enviado para servidor nenhum, o que importa quando você está escrevendo notas internas, rascunhos de documentação ou qualquer texto que ainda não deveria sair do seu computador. Essa combinação de praticidade e segurança é o que torna o Markdown tão presente em ferramentas de escrita técnica modernas, do primeiro rascunho até a publicação final do documento.
Para quem está começando, uma boa forma de aprender é escrever um README simples e ir vendo a prévia. Comece com um título, um parágrafo de introdução, uma lista do que o projeto faz e um bloco de código com o comando de instalação. Em poucos minutos você cobre os elementos mais usados e ganha confiança. À medida que precisar, acrescente tabelas, links e citações. O Markdown recompensa quem escreve com regularidade, porque a sintaxe é curta e logo vira automática.
Quando usar a ferramenta do ValorFinal
Use o Markdown preview para escrever Markdown e ver a prévia em tempo real, com contagem de palavras, títulos e links, e download em .md. Para formatar blocos de código que vão no documento, o formatador de código ajuda. Explore também as outras ferramentas de tecnologia.
Fontes oficiais
- CommonMark: especificação padronizada do Markdown.
- GitHub Flavored Markdown (GFM): extensão com tabelas e listas de tarefas.
- MDN (HTML): para entender o HTML que o Markdown gera.
Conclusão
Markdown é simples, portátil e legível mesmo sem renderizar, o que explica sua presença em README, documentação e plataformas de desenvolvimento. Conhecer a sintaxe básica e lembrar que CommonMark e GFM podem renderizar diferente evita surpresas. Para escrever e ver o resultado, use o Markdown preview e conheça as demais ferramentas de tecnologia.