Para manter o código-fonte das tabelas Markdown legível, preencha as células com espaços e realinhe cada coluna após edições mais longas. Em um Mac com o Obsidian, edite usando o editor de tabelas nativo e depois inspecione o modo Source. O preenchimento com espaços no código-fonte e o alinhamento do texto renderizado precisam ser verificados separadamente.

Este fluxo de trabalho serve para quem mantém uma pequena tabela Markdown em uma nota no computador: uma lista de leitura, um inventário de artigos de papelaria ou uma lista de verificação de projeto. O objetivo é manter o texto em si fácil de percorrer à medida que as entradas mudam, preservando uma tabela funcional no renderizador pretendido.

O que torna legível o código-fonte de uma tabela Markdown?

Uma tabela legível no código-fonte tem limites de coluna reconhecíveis, espaçamento consistente e uma linha completa por linha de texto. Seus caracteres de barra vertical ficam alinhados verticalmente quando exibidos em uma fonte monoespaçada. A documentação do GitHub afirma explicitamente que as células não precisam ter larguras iguais nem colunas perfeitamente alinhadas no código-fonte; portanto, esse alinhamento é uma conveniência de edição, não um requisito para uma tabela válida. Organizar informações com tabelas.

Por exemplo, esta tabela fictícia é compacta, mas fica mais difícil de percorrer depois que se insere um nome de item mais longo:

| Item | Finish | Count |
| --- | --- | ---: |
| Pencil | Matte | 4 |
| Large sketchbook | Linen | 12 |

Adicionar espaços torna o mesmo conteúdo mais fácil de inspecionar como texto simples:

| Item             | Finish | Count |
| ---------------- | ------ | ----: |
| Pencil           | Matte  |     4 |
| Large sketchbook | Linen  |    12 |

No GFM, os espaços entre os limites das barras verticais e o conteúdo das células são removidos. Portanto, o preenchimento com espaços não define a largura das colunas renderizadas. Os dois-pontos em ----: controlam o alinhamento à direita da coluna renderizada; os espaços antes de 4 apenas facilitam a leitura deste exemplo no código-fonte. Especificação do GitHub Flavored Markdown, tabelas.

Trate isso como duas decisões separadas: escolha o preenchimento com espaços para facilitar a leitura do código-fonte e escolha os dois-pontos na linha delimitadora para alinhar o texto renderizado. Se o único problema forem as barras verticais desalinhadas no editor, mudar os dois-pontos não resolverá a questão.

Qual renderizador vai ler a tabela?

Tabelas com barras verticais são uma extensão, não um recurso do CommonMark básico. A especificação atual do CommonMark corresponde à versão 0.31.2, enquanto a especificação publicada do GFM pelo GitHub define explicitamente as tabelas como uma extensão do CommonMark. Um renderizador descrito apenas como compatível com CommonMark não promete, por isso, oferecer suporte a tabelas com barras verticais. Verifique se ele também oferece suporte a uma extensão de tabelas. Especificação do CommonMark, Especificação do GitHub Flavored Markdown.

As distinções a seguir são relevantes ao transferir uma nota entre aplicativos:

Destino Comportamento documentado Escolha prática
CommonMark básico A especificação básica não inclui sintaxe de tabela com barras verticais Confirme se há uma extensão de tabelas disponível
GitHub O guia de tabelas exige pelo menos três hífens em cada célula delimitadora Use --- ou mais
Obsidian O guia de tabelas aceita no mínimo dois hífens e não exige que as células estejam alinhadas no código-fonte Use três ou mais se também for usar no GitHub

Os requisitos de hífens acima vêm dos guias dos respectivos produtos. Usar pelo menos três é uma convenção compartilhada conveniente para esses dois destinos; isso não torna todos os renderizadores Markdown equivalentes. Documentação de tabelas do GitHub, Sintaxe de formatação avançada do Obsidian.

Para uma tabela destinada ao Obsidian e ao GitHub, use barras verticais no início e no fim, espaços comuns para preencher e uma linha em branco antes e depois da tabela. O guia do GitHub pede uma linha em branco antes da tabela; a especificação do GFM documenta que uma linha vazia encerra uma tabela. Manter explícitos os dois limites também facilita identificar o código-fonte. Documentação de tabelas do GitHub, Limites de tabelas no GFM.

Como manter a tabela no Obsidian em um Mac

O Obsidian oferece uma opção útil para quem quer editar células com facilidade e depois ter um Markdown legível. As notas de lançamento da versão 1.5.8 para computador introduziram a formatação automática de tabelas durante a digitação e mencionaram especificamente colunas mais organizadas ao serem vistas no modo Source. Esse é um comportamento documentado do editor, não um recurso da sintaxe Markdown. Notas de lançamento do Obsidian 1.5.8 para computador.

Siga esta sequência para uma nota comum:

  1. Abra a nota em Live Preview. Se necessário, selecione esse modo pelo ícone de status do editor.
  2. Insira uma tabela usando o comando Insert Table ou clique com o botão direito e escolha Insert → Table.
  3. Insira ou revise o conteúdo das células no editor de tabelas. Clique com o botão direito na tabela quando precisar adicionar, excluir, mover ou ordenar linhas e colunas.
  4. Selecione Source mode pelo ícone de status e inspecione o Markdown resultante.
  5. Mude para Reading view para conferir a tabela exibida.

Os controles de modo estão documentados em Visualizações e modo de edição; as operações de inserção de tabelas e do menu de contexto estão documentadas em Sintaxe de formatação avançada.

Para alternar repetidamente entre os modos, atribua um atalho de teclado a Toggle Live Preview/Source mode. No macOS, Cmd+E alterna entre as visualizações de leitura e edição; use o comando de modo específico quando quiser alternar entre os dois modos de edição. Visualizações e modo de edição do Obsidian.

Se a digitação direta no Source mode deixar o preenchimento com espaços irregular, volte ao editor de tabelas nativo para fazer outras edições e inspecione o código-fonte depois. A documentação citada confirma a formatação automática de tabelas e a inspeção precisa do código-fonte, mas não estabelece uma garantia universal de que toda edição arbitrária no código-fonte será preenchida novamente com espaços imediatamente. Para uma tabela pequena que continuar irregular, o método manual abaixo oferece controle direto.

Como realinhar as colunas no código-fonte após uma edição mais longa

Use uma regra simples: deixe cada coluna no código-fonte larga o suficiente para a entrada atual mais longa, incluindo o cabeçalho. Adicione preenchimento com espaços às outras células da coluna. Recalcule quando uma entrada ficar mais longa do que o espaço disponível.

Veja um exemplo detalhado usando apenas texto ASCII simples. Comece com esta tabela:

| Item   | Finish | Count |
| ------ | ------ | ----: |
| Pencil | Matte  |     4 |
| Folder | Linen  |    12 |

Agora substitua Folder por Large sketchbook. O novo item tem 16 caracteres, então a primeira coluna precisa de uma área de conteúdo com 16 caracteres. Deixe um espaço imediatamente dentro de cada barra vertical de limite e, em seguida, adicione espaços finais suficientes para preencher essa área:

  • Item tem 4 caracteres; portanto, adicione 12 espaços de preenchimento depois dele, seguidos pelo espaço de limite.
  • Pencil tem 6 caracteres; portanto, adicione 10 espaços de preenchimento depois dele, seguidos pelo espaço de limite.
  • Large sketchbook preenche a área de 16 caracteres; portanto, só precisa do espaço de limite depois dele.
  • Amplie a primeira célula delimitadora para 16 hífens, como guia visual correspondente.

O resultado é a tabela preenchida com espaços mostrada anteriormente. Somente a primeira coluna precisou ser alargada. As outras colunas mantêm o espaçamento e os marcadores de alinhamento.

Esta é uma instrução de formatação manual para o exemplo ASCII apresentado, não um algoritmo geral de largura de caracteres. Na edição do dia a dia, inspecione o resultado em uma exibição do código-fonte com fonte monoespaçada. Se as células contiverem formatação em linha substancial, avalie a largura no código-fonte com base nos caracteres efetivamente escritos, incluindo pontuação como crases e asteriscos.

Depois de um conjunto de edições, alinhe a tabela uma vez em vez de ajustar cada linha a cada tecla digitada. Se as entradas frequentemente virarem parágrafos, considere manter apenas um rótulo curto na tabela e mover a explicação para o texto corrido abaixo. Isso reduz o trabalho de manutenção dos espaços em branco sem encurtar as informações subjacentes.

O que verificar quando uma tabela quebra?

Comece pela estrutura antes de ajustar os espaços. No GFM, as linhas de cabeçalho e delimitadora precisam ter a mesma quantidade de células. As linhas do corpo com células insuficientes recebem células vazias; as células excedentes são ignoradas. Portanto, uma tabela pode parecer plausível e ainda assim omitir conteúdo no resultado renderizado. Regras de análise de tabelas do GFM.

Use esta sequência de diagnóstico após uma edição substancial:

  1. Compare as linhas de cabeçalho e delimitadora. Dê a cada cabeçalho uma célula delimitadora correspondente.
  2. Inspecione cada linha do corpo. Mantenha a quantidade de células desejada, inclusive quando um valor estiver vazio.
  3. Procure barras verticais literais no conteúdo. Uma barra vertical sem escape pode ser interpretada como outro limite.
  4. Inspecione os limites das linhas. Mantenha cada linha da tabela em uma única linha do código-fonte e evite linhas em branco dentro da tabela.
  5. Confira a visualização do destino. Verifique os valores exibidos e também a aparência da tabela.

Para barras verticais literais, o GitHub documenta a inclusão de uma barra invertida antes do caractere. Este exemplo completo mantém Blue | Green dentro de uma única célula:

| Item   | Options       |
| ------ | ------------- |
| Folder | Blue \| Green |

O escape é estrutural; adicionar mais espaços ao redor de uma barra vertical sem escape não resolverá o problema. Exemplo do GitHub com barra vertical literal.

O Obsidian também documenta o escape da barra vertical usada em um alias de link interno dentro de uma tabela. Essa é uma consideração específica da sintaxe do Obsidian; portanto, um alias com escape não comprova, por si só, um comportamento equivalente dos links no GitHub. Orientações de formatação de tabelas do Obsidian.

Não pressione Enter no meio de uma célula longa para fazer o código-fonte parecer mais estreito. As tabelas do GFM aceitam conteúdo em linha e excluem elementos em bloco; elas não oferecem um formato geral para células com várias linhas no código-fonte. Mova explicações longas para fora da tabela quando as linhas de uma só linha se tornarem impraticáveis. Regras de conteúdo de tabelas do GFM.

Mantenha a rotina de manutenção simples: conclua as alterações de conteúdo, inspecione os limites das células, preencha com espaços as colunas afetadas e revise a tabela renderizada. No Obsidian, começar pelo editor de tabelas nativo e depois usar Source mode é uma opção prática. O preenchimento manual com espaços continua sendo útil quando você quer um layout específico em texto simples.

Fontes