Neste artigo
O que são tabelas Markdown?
As tabelas Markdown usam caracteres de barra vertical (|) e hífens (-) para criar dados tabulares estruturados em documentos de texto simples. Elas fazem parte do GitHub Flavored Markdown (GFM) e são suportadas pela maioria dos renderizadores de Markdown, incluindo GitHub, GitLab, VS Code e geradores de sites estáticos.
As tabelas em Markdown são projetadas para apresentação simples de dados — cabeçalhos de coluna, linha separadora e linhas de dados. Elas são renderizadas como tabelas HTML adequadas na saída, tornando-as ideais para documentação, arquivos README e escrita técnica sem nenhum conhecimento de HTML.
Sintaxe de tabelas Markdown
Uma tabela Markdown consiste em três partes: a linha de cabeçalho, a linha separadora e uma ou mais linhas de dados.
- Linha de cabeçalho — a primeira linha define os nomes das colunas, separados por caracteres de barra vertical (|). As barras verticais iniciais e finais são opcionais, mas recomendadas para maior clareza.
- Linha separadora — a segunda linha usa hífens (---) entre barras verticais para separar o cabeçalho dos dados. São necessários pelo menos três hífens por coluna.
- Linhas de dados — cada linha subsequente contém valores de célula separados por barras verticais. As células não precisam se alinhar visualmente, embora colunas alinhadas melhorem a legibilidade do código-fonte.
- Escapar barras verticais — se o conteúdo de uma célula contiver um caractere de barra vertical literal, escape-o com uma barra invertida (\|) para evitar que seja interpretado como separador de colunas.
Opções de alinhamento de colunas
O alinhamento de colunas é controlado adicionando dois-pontos à linha separadora. Isso determina como o texto é alinhado dentro de cada coluna.
- Alinhamento à esquerda (padrão) — use :--- ou --- no separador. O texto se alinha à borda esquerda da coluna. Este é o padrão quando nenhum dois-pontos é especificado.
- Alinhamento centralizado — use :---: no separador. O texto é centralizado dentro da coluna. Útil para rótulos de status, categorias ou valores curtos.
- Alinhamento à direita — use ---: no separador. O texto se alinha à borda direita. Ideal para valores numéricos, preços, contagens e medidas.
Experimente gratuitamente — sem cadastro
Gerar tabelas Markdown →Casos de uso comuns
As tabelas Markdown são usadas onde dados estruturados precisam ser apresentados na documentação.
- Documentação README — tabelas de comparação de recursos do projeto, requisitos de instalação, plataformas suportadas e matrizes de compatibilidade de versão
- Documentação de API — referências de endpoints com tabelas de método, caminho, descrição e parâmetros para cada rota
- Tabelas de comparação — comparações de recursos lado a lado, faixas de preço e avaliações de ferramentas em posts de blog e análises técnicas
- Changelogs — tabelas de histórico de versão com data, número de versão e descrição das alterações para cada lançamento
Dicas e melhores práticas
Seguir essas diretrizes ajuda a manter suas tabelas Markdown legíveis tanto na forma de código-fonte quanto na renderizada.
- Mantenha as colunas alinhadas no código-fonte — preencha as células com espaços para que as colunas se alinhem visualmente. A maioria dos editores e nosso gerador fazem isso automaticamente. O código-fonte alinhado é muito mais fácil de revisar em pull requests.
- Evite conteúdo complexo nas células — tabelas Markdown não suportam conteúdo de células em múltiplas linhas, elementos de bloco ou tabelas aninhadas. Mantenha o conteúdo das células curto e simples. Para dados complexos, considere usar tabelas HTML.
- Limite o número de colunas — tabelas com mais de 5-6 colunas ficam difíceis de ler em telas menores. Considere dividir tabelas largas em várias tabelas mais focadas ou usar um formato diferente para dados muito amplos.
Perguntas frequentes
Existe um limite para o conteúdo das células nas tabelas Markdown?
Não há limite técnico de caracteres para o conteúdo das células, mas as células de tabelas Markdown são apenas de uma linha. Você não pode incluir quebras de linha, parágrafos ou elementos de nível de bloco como listas dentro de uma célula. Para conteúdo complexo de células, use tabelas HTML com elementos <td> que suportam qualquer conteúdo HTML.
Posso mesclar células em tabelas Markdown?
Não. As tabelas Markdown padrão não suportam colspan ou rowspan — cada linha deve ter o mesmo número de colunas. A mesclagem de células requer tabelas HTML. Se precisar de células mescladas, escreva a tabela em HTML e incorpore-a diretamente no seu documento Markdown.
Posso aninhar tabelas dentro de tabelas Markdown?
Não. As tabelas Markdown não podem ser aninhadas. Cada tabela é uma grade plana de linhas e colunas. Se precisar de dados hierárquicos, considere usar listas aninhadas, tabelas separadas com títulos ou tabelas HTML com elementos <table> aninhados.