Markdown tabelas: gere-as em vez de contar tubos

A sintaxe, em um exemplo

                | Tool          | Input       | Offline |
| :------------ | :---------: | ------: |
| YAML to JSON  | YAML        | yes     |
| JWT decoder   | JWT         | yes     |
              

A primeira linha é o cabeçalho, a segunda é a linha delimitadora e tudo o que vem depois são dados. Os dois pontos na linha delimitadora definem o alinhamento: `:---` esquerda, `:---:` centro, `---:` direita. GitHub e a maioria dos renderizadores aceitam tubos iniciais e finais como opcionais, mas incluí-los mantém o texto bruto legível em um editor.

As três coisas que quebram mesas

• Um tubo dentro de uma célula — escape dele como `\|`, ou a linha será dividida em uma coluna a mais.
• Uma linha delimitadora com o número errado de colunas — o cabeçalho muda e a tabela fica desalinhada.
• Uma linha em branco dentro da tabela — o renderizador a trata como o final da tabela e imprime o restante como texto.

O escape é mais importante para código e expressões regulares em células: `a|b` e `\bfoo\b` precisam de atenção antes de poderem viver felizes dentro de uma mesa.

Obtendo dados de uma planilha

O fluxo de trabalho natural é colar uma seleção de uma planilha ou uma exportação CSV e deixar o gerador fazer a cotação e o alinhamento. Isso é mais rápido e menos sujeito a erros do que digitar linhas e também lida com casos enfadonhos – larguras de coluna variáveis, números que devem ser alinhados à direita, células que contêm vírgulas. Corte as colunas vazias antes de colar para evitar uma tabela com colunas fantasmas que são renderizadas como lacunas.

Quando não usar uma mesa

As tabelas são para comparações: matrizes de recursos, referências de sinalizadores, listas de compatibilidade, variáveis ​​de ambiente. Eles são ruins para prosa, ruins para descrições longas e dolorosos em telas estreitas porque o markdown não tem comportamento responsivo - o renderizador rola horizontalmente ou comprime as colunas em fatias ilegíveis. Se uma célula precisar de um parágrafo, use uma lista de definições, um título por entrada ou uma lista com marcadores. Uma tabela que ninguém consegue ler no telefone é pior do que a lista que ela substituiu.

Gere e cole em qualquer lugar

A saída é uma marcação simples, então ela vai direto para um README, uma descrição de pull request, uma página wiki, um ticket do Jira ou um comentário. O gerador de tabela markdown YamlBox é executado no navegador, alinha colunas para você, escapa de pipes e continua trabalhando off-line — para que você possa colar dados internos sem publicá-los em qualquer lugar.