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.

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.