Cola de Markdown

Sobre a Cola de Markdown

Qual a diferença entre CommonMark e GitHub Flavored Markdown?

CommonMark é a especificação inequívoca de Markdown publicada em 2014 que resolve as dezenas de casos ambíguos deixados vagos na descrição original de John Gruber, de 2004. GitHub Flavored Markdown (GFM) é um superconjunto estrito de CommonMark: tudo que CommonMark suporta é suportado em GFM de forma idêntica, e a especificação GFM adiciona tabelas, listas de tarefas, tachado, autolinks e algumas regras extras. Os recursos mais novos específicos do GitHub - avisos (> [!NOTE]), seções recolhíveis, código cercado com realce e códigos de emoji - não fazem parte estritamente do GFM, mas o GitHub renderiza mesmo assim. Esta cola os rotula como 'Extensões GFM' por conveniência, mas nem todo motor Markdown vai renderizá-los; para documentos portáveis, use CommonMark puro.

Por que minha lista não está renderizando direito?

O problema mais comum de renderização do Markdown é a falta da linha em branco que separa a lista do parágrafo ao redor. CommonMark exige linha em branco antes de qualquer lista; caso contrário o primeiro item fica colado ao texto anterior como um parágrafo só. O segundo problema mais comum é a indentação de aninhamento: cada nível deve ser indentado exatamente pela largura do marcador mais um espaço (normalmente dois espaços para listas sem ordem, três ou quatro para ordenadas). Se um item aninhado se recusa a indentar, verifique se a linha pai não termina com espaço sobrando e se você usou espaços, não tabs. Por fim, alguns parsers legados não aceitam números diferentes de 1 como primeiro item ordenado; CommonMark aceita qualquer número e renderiza em ordem.

Como escapo caracteres especiais do Markdown?

Coloque uma barra invertida antes de qualquer caractere que o Markdown interpretaria: \*não itálico\*, \#não-título, \[não-link\]. Os caracteres escapáveis são: \ ` * _ { } [ ] ( ) # + - . ! | > e ~. Fora deles, a barra fica como está. O caso mais delicado é querer crases literais dentro de código em linha: envolva o código com uma sequência maior de crases, então ``código com ` dentro`` vira <code>código com ` dentro</code>. Para as próprias barras invertidas, duplique: \\. A maioria dos editores com visualização Markdown mostra imediatamente se o escape funcionou, então use uma visualização ao vivo na dúvida.

Os avisos do GitHub são portáveis para outras ferramentas?

A sintaxe de avisos > [!NOTE] / [!TIP] / [!WARNING] / [!IMPORTANT] / [!CAUTION] foi introduzida pelo GitHub no final de 2023 e adotada logo depois pelo GitLab. Renderizadores que não a implementaram (a maioria dos geradores estáticos, Notion e editores Markdown antigos) tratam o bloco como uma citação comum, o que é elegante: o aviso continua lendo certo, só sem a faixa colorida. Se você publica seus docs em uma plataforma como MkDocs, Hugo ou Jekyll, prefira a sintaxe nativa de admonição (por exemplo !!! note ... no MkDocs Material). Para máxima portabilidade, escreva avisos como citações com prefixo em negrito: > **Nota:** ... que renderiza com bom senso em todo lugar.

Como escrevo equações matemáticas em Markdown?

Matemática em linha vai entre cifrões simples: $E = mc^2$. Matemática em bloco vai entre cifrões duplos em linhas próprias, como $$\int_0^1 x^2 dx$$. A renderização real depende do motor: GitHub, GitLab, Obsidian, Notion e Quarto suportam TeX/LaTeX nativamente via KaTeX ou MathJax; CommonMark clássico não. Se você publica por um gerador estático, instale um plugin de matemática (rehype-katex para unified, mkdocs-material com arithmatex para MkDocs, hugo-katex para Hugo). Escape cifrões isolados que devem aparecer como moeda com barra invertida: \$5 - caso contrário o motor pode tentar entrar em modo matemático e produzir saída estranha.

Como faço uma tabela em Markdown e alinho as colunas?

Tabelas usam barras verticais para separar colunas e uma linha divisória de traços para separar o cabeçalho do corpo: | Nome | Pontos | na primeira linha, |------|--------| na segunda, e depois uma linha | valor | valor | por registro. Os traços só precisam existir, não precisam estar alinhados ao texto. Para controlar o alinhamento das colunas, adicione dois-pontos à linha divisória: |:---| é esquerda, |:--:| é centro e |---:| é direita. Assim uma linha como |:--|:-:|--:| dá colunas à esquerda, ao centro e à direita. Você não precisa de barras externas, mas elas deixam o código mais fácil de ler e copiar. Se uma célula precisar conter uma barra vertical literal, escape-a com uma barra invertida como \| para que o parser não a trate como separador de coluna; esse é o erro mais comum ao colocar código ou regex dentro de uma célula. Tabelas são uma extensão do GFM, então GitHub, GitLab e Obsidian as renderizam, mas o CommonMark estrito não.

Como adiciono uma quebra de linha em Markdown?

O Markdown tem três formas de forçar uma quebra de linha dentro de um parágrafo. O método clássico é terminar a linha com dois espaços finais e apertar Enter; o problema é que o espaço final é invisível e muitos editores o removem automaticamente. O método mais confiável do GFM é uma barra invertida no fim da linha, que é visível no código e sobrevive ao corte de espaços. A terceira via é a tag HTML <br>, que funciona em praticamente todos os renderizadores, incluindo CommonMark estrito. Para iniciar um parágrafo totalmente novo em vez de uma quebra suave, deixe uma linha completamente em branco entre os dois blocos de texto; é o separador mais portátil de todos e o que você vai querer na maioria das vezes.

Quais recursos do Markdown funcionam no GitHub, GitLab e CommonMark?

Depende da construção, que é exatamente o que as insígnias de compatibilidade de cada card mostram. Negrito, itálico, títulos, links, imagens, citações, listas e código cercado são CommonMark básico e renderizam igual em todo lugar. Tabelas, listas de tarefas, tachado e autolinks de URL nua são extensões do GFM: GitHub, GitLab e Obsidian suportam, mas CommonMark estrito não. Notas de rodapé e matemática TeX/LaTeX renderizam no GitHub, GitLab e Obsidian, mas não em CommonMark puro. Os avisos do GitHub (> [!NOTE]) funcionam no GitHub, GitLab e Obsidian (o Obsidian tem avisos nativos), mas degradam para uma citação simples em outros lugares. @menções e referências #issue são específicas do GitHub. Listas de definições (termo / : definição) são um recurso do Markdown Extra / pandoc e não renderizam em nenhuma das quatro. Para documentos que precisam sobreviver a qualquer pipeline, ative "Somente portátil" para filtrar a folha para o subconjunto seguro em CommonMark.

Por que esta cola carrega muito mais rápido que outros sites de documentação?

Três motivos. Primeiro, cada card é renderizado no servidor como HTML estático; não há parser Markdown no cliente esperando, nem bundles de Mermaid, nem JavaScript de syntax highlighting - os bytes que você vê são os bytes que o servidor enviou. Segundo, a busca usa um filtro vanilla com querySelectorAll sobre algumas dezenas de cards, então mesmo num celular modesto cada tecla atualiza o DOM em menos de um milissegundo. Terceiro, a página é cacheada de forma agressiva pela infraestrutura WuTools: HTML 10 dias, o pequeno JS de filtro um ano, e os ícones SVG também. Quando um visitante recorrente tem a página em cache, a cola aparece praticamente no tempo que o navegador leva para pintar um quadro.