Visualizador gratuito de Markdown on-line

Guia Rápido de Markdown

Sobre o Markdown

O Markdown foi criado por John Gruber, o autor por trás do weblog Daring Fireball, com feedback de design substancial de Aaron Swartz. A primeira versão pública, 1.0, foi anunciada no site de Gruber a 9 de Março de 2004; a versão 1.0.1, a versão de referência canónica, seguiu a 17 de Dezembro de 2004 e ainda é a versão ligada a partir de daringfireball.net/projects/markdown. Markdown é duas coisas ao mesmo tempo: uma sintaxe de formatação em texto puro e o script Perl original que converte essa sintaxe em HTML. O objectivo declarado de Gruber era que o texto fonte fosse legível tal como está, um documento Markdown aberto num editor de texto puro deve parecer-se com um e-mail cuidadosamente formatado, não uma sopa de tags. Essa restrição de legibilidade é a linha filosófica que separa o Markdown dos formatos baseados em XML e da marcação mais pesada como LaTeX, e é a razão pela qual cada extensão posterior teve de se justificar em termos de quão mal perturba a fonte.

Gruber credita extensamente Swartz nos agradecimentos do Markdown: «Aaron Swartz merece uma enorme quantidade de crédito pelo seu feedback no design da sintaxe de formatação do Markdown.» Swartz tinha escrito antes uma marcação leve relacionada chamada atx (2002), que contribuiu o agora familiar estilo de cabeçalho # e ##: por vezes ainda chamado «atx-style headings» nas specs de parsers. O envolvimento de Swartz é uma peça do seu legado mais amplo: co-construiu o RSS 1.0 quando era adolescente, foi co-proprietário do Reddit até 2007, e continuou a influenciar os padrões da web aberta até à sua morte em 2013. Uma curiosidade que vale a pena perceber bem: a extensão de ficheiro .md é agora quase universal, mas a ferramenta original de Gruber usava .text: a migração para .md foi uma convenção comunitária que se afirmou assim que o Markdown saiu do nicho dos blogs.

Porque é que o Markdown ganhou a web

Uma linguagem de marcação ganha ao ser adoptada pelas plataformas que publicam a maior parte do texto do mundo. Numa janela apertada de cinco anos, o Markdown foi adoptado pelas plataformas que vieram a dominar a discussão longa, a colaboração de código e a documentação para programadores. O Stack Overflow lançou-se a 15 de Setembro de 2008 com Markdown como sintaxe de formatação para perguntas, respostas e comentários, usando um editor chamado WMD (Wysiwym Markdown) por John Fraser da AttackLab; a equipa do Stack Overflow reescreveu-o depois como o editor open-source PageDown mantido em github.com/StackExchange/pagedown. O Reddit, fundado por Steve Huffman e Alexis Ohanian em 2005 com Aaron Swartz a juntar-se pouco depois, lançou Markdown para comentários pouco após o lançamento e levou a sintaxe a um público muito mais amplo, não programador. O GitHub lançou-se em 2008 e em menos de um ano já renderizava Markdown em README.md e comentários de issues; em 2009 começou a documentar e a lançar o seu próprio dialecto, o GitHub Flavored Markdown. O Discord, lançado em Maio de 2015, adoptou uma sintaxe de chat com sabor Markdown para negrito, itálico, rasurado, código inline, code fences e blockquotes, o que a maioria dos não programadores com menos de 25 anos agora pensa como «pôr estrelas à volta de algo». A competência acumula-se: um autor que aprende Markdown uma vez pode escrever posts de blog em Jekyll/Hugo/Eleventy, documentação em MkDocs/Docusaurus/Read the Docs, apresentações em Marp e Reveal.js, notas em Obsidian/Bear/Logseq/Notion, chat em Slack e Discord, e documentação de código fonte em essencialmente todos os projectos open-source modernos.

CommonMark, corrigir a sub-especificação

A descrição original da sintaxe de Gruber de 2004 era famosamente informal, um documento em prosa com exemplos, não uma gramática. Deixou dezenas de casos limite por especificar («como interage a ênfase com underscores no meio de uma palavra?»; «uma lista dentro de um blockquote fecha o blockquote?»; «o que conta como lista apertada vs lista solta?»), e Gruber nunca lançou um parser de referência além do seu script Perl, cujo comportamento era idiossincrático de formas que outros implementadores tinham de copiar ou sobrescrever. O resultado no início da década de 2010 foi que o GitHub, Reddit, Stack Overflow, Pandoc e o parser C Discount renderizavam todos a mesma fonte Markdown ligeiramente diferente, e a mesma entrada podia partir-se entre plataformas.

Em 2012, o co-fundador do Stack Overflow Jeff Atwood (nessa altura a dirigir o Discourse) e o autor do Pandoc John MacFarlane começaram um esforço para escrever uma especificação real e testável. Foram acompanhados por David Greenspan (Meteor), Vicent Marti (GitHub), Neil Williams (Reddit) e Benjamin Dumke-von der Ehe (Stack Exchange). O projecto foi lançado publicamente em Setembro de 2014 como «Standard Markdown»; em poucos dias Gruber objectou ao nome em e-mail privado, Atwood escreveu um post público a explicar a alteração, e o projecto foi rebaptizado «CommonMark». A primeira release numerada chegou a 25 de Outubro de 2014. A versão actualmente publicada é o CommonMark 0.31.2, lançado a 28 de Janeiro de 2024, uma «1.0» foi prometida para 2019 e não chegou porque um pequeno número de casos limite patológicos (notavelmente em torno do parsing de ênfase e da incrustação HTML) não produziram resoluções unânimes. Na prática, 0.31.2 é tratado como estável para produção. A spec CommonMark é invulgar por ela própria ser um documento CommonMark, com mais de 600 casos de teste executáveis em linha; um parser reclama conformidade ao passar nesses testes.

GitHub Flavored Markdown, cinco extensões por cima

A especificação formal GFM, publicada em 2017 e mais recentemente versionada como 0.29-gfm a 6 de Abril de 2019, define cinco extensões em cima do CommonMark: tabelas (blocos delimitados por barras verticais com uma linha de delimitador a usar traços e : para alinhamento por coluna); itens de lista de tarefas (entradas de lista que começam por [ ] para não marcadas ou [x] para marcadas, renderizadas como checkboxes HTML desactivadas, o GitHub adicionalmente permite a utilizadores autenticados alterná-las clicando, o que é uma camada UX por cima da spec, não parte da spec em si); rasurado (envolver texto em ~~ produz <del>: o CommonMark em si não especifica isto); extensão autolinks (URLs nuas e endereços de email no texto corrente são auto-ligados, onde o CommonMark só o faz para autolinks explícitos com sinais de menor/maior); e HTML cru proibido (uma restrição de segurança que remove <script>, <iframe>, <style>, <title>, <plaintext>, <textarea>, <xmp>, <noembed>, <noframes> e um punhado de outras tags perigosas). Uma sexta funcionalidade comummente atribuída ao GFM mas que vale a pena tratar com cuidado são os blocos de código com fences com identificadores de linguagem: os blocos de código com fences são parte do próprio CommonMark; a dica de linguagem depois da fence de abertura é também CommonMark; o syntax highlighting que o GitHub aplica depois com base nessa dica é comportamento de renderização do GitHub, não a spec. O renderizador do GitHub também executa pós-processamento adicional, sanitização HTML via o seu gem interno html-pipeline, expansão de shortcodes de emoji (:smile:), auto-linking @user e #issue: nenhum dos quais está em GFM em si.

Os principais parsers

marked.js foi criado por Christopher Jeffrey, com o copyright original datado de 2011, e tem sido mantido pela organização GitHub markedjs desde 2018. É um design lexer-depois-parser de passagem única que prioriza velocidade bruta; os docs posicionam-no explicitamente como um «low-level compiler for parsing markdown without caching or blocking». É o parser que este previewer usa actualmente para o render ao vivo. Marked é pequeno, rápido, extensível através de hooks de tokens, e um dos projectos markdown mais estrelados no GitHub (~36k estrelas).

markdown-it foi lançado em 2014 por Vitaly Puzrin e Alex Kocharin. Os dois tinham contribuído antes quase todo o código a um parser chamado Remarkable; quando disputas de liderança bloquearam o progresso, reorganizaram a mesma autoria em torno do markdown-it. O projecto anuncia 100% conformidade CommonMark com interruptores GFM opcionais para tabelas e rasurado, mais um ecossistema de plugins agressivo (markdown-it-footnote, markdown-it-emoji, markdown-it-attrs, markdown-it-anchor, markdown-it-task-lists e várias centenas de outros). É o parser usado pelo preview Markdown incorporado do VS Code, pela UI web do GitLab, e por uma longa lista de geradores de sites estáticos incluindo o Eleventy.

remark / unified.js não é um parser único mas uma framework de transformação de árvores. O colectivo unified, iniciado por volta de 2014, define uma spec de árvore sintáctica abstracta chamada mdast (Markdown Abstract Syntax Tree); remark faz parse de Markdown em mdast, plugins manipulam a árvore, e remark-rehype converte mdast para hast (a AST HTML) para emissão. O modelo é mais lento que marked mas vastamente mais combinável. Utilizadores notáveis incluem Prettier (que formata Markdown com remark), Gatsby, MDN, o pipeline de documentação do Node.js, e o linter de linguagem inclusiva alex. O colectivo unified lista 312 projectos e cerca de 6,3 mil milhões de downloads npm mensais em todos os seus pacotes.

MDX, primeiro committed no final de 2017 por John Otander e outros ligados à empresa de ferramentas de design Compositor, foi anunciado publicamente no ZEIT Day 2018 e lançou a 1.0 a 11 de Abril de 2019. MDX combina conteúdo Markdown com componentes JSX, por isso um autor pode largar um <Chart /> ou um <Tweet id="123" /> directamente na prosa. Alimenta os docs do Next.js, Docusaurus e a maioria dos sites de documentação baseados em React. MDX tem o seu próprio parser distinto do CommonMark; v1 era baseado em remark, v2+ usa uma gramática MDX dedicada para tratar correctamente expressões JSX dentro do contexto de parágrafo.

Pandoc, o conversor universal

O Pandoc foi lançado por John MacFarlane, então professor de filosofia na Universidade da Califórnia, Berkeley, a 10 de Agosto de 2006. É escrito em Haskell, e o seu design centra-se em fazer parse de qualquer um de cerca de 30 formatos de entrada (Markdown, reStructuredText, HTML, LaTeX, DocBook, Textile, marcação MediaWiki e DokuWiki, Org-mode, Microsoft Word .docx, OpenDocument, EPUB, JATS XML, Jupyter .ipynb e outros) num modelo de documento abstracto partilhado, e depois renderizar esse modelo em cerca de 40 formatos de saída (HTML, PDF via LaTeX ou wkhtmltopdf, .docx, .odt, ePub2/3, formatos de slides incluindo Beamer e reveal.js, e muitos mais). É ubíquo na publicação académica e técnica porque transporta citações através de CSL JSON / BibTeX e resolve-as em referências formatadas para qualquer um dos principais estilos de citação. O dialecto Markdown que o Pandoc faz parse por defeito («Pandoc Markdown») é em si um superconjunto de CommonMark com extensões para notas de rodapé, listas de definições, divs com fence, matemática (estilo LaTeX $...$ e $$...$$) e legendas de tabelas. O Pandoc está licenciado sob GPL v2-or-later e é o que a maioria dos departamentos académicos usa para compilar manuscritos Markdown em documentos Word prontos para revistas.

MultiMarkdown, Markdown Extra e SmartyPants

Dois dialectos de extensão anteriores precedem o CommonMark e influenciaram tanto o GFM como o Pandoc. MultiMarkdown foi criado por Fletcher T. Penney com um lançamento inicial em Maio de 2007 (o trabalho do projecto começou em 2005-2006), motivado pela escrita académica, Penney queria um Markdown capaz de produzir um manuscrito publicável com notas de rodapé, citações, matemática, listas de definições e metadados de documento ao estilo YAML. MultiMarkdown introduziu ou popularizou as tabelas com carácter pipe, os marcadores de notas de rodapé [^id], a notação matemática, os blocos de metadados ao nível do documento no topo dos ficheiros, e legendas de imagens e tabelas. Markdown Extra foi criado por Michel Fortin (autor do PHP Markdown) em 2005-2006 e adicionou tabelas com pipe, blocos de código com fence usando ~~~ (mais tarde também ```), notas de rodapé, listas de definições, abreviaturas, e a sintaxe de atributo {#id .class} para cabeçalhos. A sua contribuição mais distintiva foi a flexibilização das regras de Markdown-dentro-de-HTML, o atributo markdown="1" que permite aninhar Markdown dentro de um bloco HTML. Várias decisões de design do CommonMark e GFM em torno de código com fence e tabelas remontam ao Markdown Extra. Separadamente, SmartyPants: o próprio companheiro tipográfico de Gruber de 2002, realiza substituições tipográficas: aspas ASCII rectas tornam-se aspas curvas, traços duplos e triplos tornam-se travessões e meios-travessões, três pontos tornam-se uma verdadeira reticência. Markdown trata da estrutura; SmartyPants trata do polimento; muitos parsers agrupam comportamento ao estilo SmartyPants como passo de pós-processamento (markdown-it-smartypants, remark-smartypants), e o Pandoc tem-no incorporado por trás de uma flag --smart.

Armadilhas comuns, dez coisas que mordem novos autores

Um previewer ao vivo torna a maioria das surpresas de parsing óbvias imediatamente, mas compreender porque acontecem ajuda um autor a obter a fonte correcta à primeira.

1. Conversão de aspas inteligentes que parte amostras de código. Filtros ao estilo SmartyPants convertem alegremente aspas dentro do que parece ser prosa (incluindo, por vezes, dentro de spans de código inline ou valores de atributo HTML) deixando-o com marcação partida. A maioria dos parsers modernos exclui spans de código da substituição tipográfica, mas plataformas de blog com pipelines personalizados muitas vezes não o fazem.
2. A detecção de marcadores de lista é sensível a espaços em branco. Misturar -, * e + dentro da mesma lista, indentar parágrafos de continuação de lista por menos do que o marcador exige, ou pôr uma linha em branco entre itens de lista pode virar uma lista apertada numa lista solta (cada item envolvido em tags <p>), uma diferença invisível na fonte mas dramática na saída.
3. Excesso de zelo de autolink. O auto-linking ao estilo GFM transforma qualquer URL nua num link, o que é normalmente o que se pretende, mas também pode estragar URLs dentro do que devia ter sido um span de código, ou URLs com parênteses (URLs da Wikipédia especialmente). A regra para «onde termina este URL?» varia entre parsers.
4. Dicas de linguagem em fences de código. O texto a seguir ao triplo-backtick de abertura, ```js vs ```javascript vs ```ts vs ```typescript: é uma dica, não uma spec. Diferentes destacadores de sintaxe reconhecem diferentes aliases; Highlight.js, Prism, Shiki e o renderizador do GitHub têm cada um os seus próprios dicionários de linguagens.
5. Tabelas que precisam de escape. Os caracteres pipe dentro de células de tabela têm de ser escapados como \|, caso contrário são lidos como separadores de coluna. Apanha qualquer um a tentar pôr um exemplo de código de uma linha dentro de uma célula de tabela.
6. Quebras de linha duras. Dentro de um parágrafo, uma única nova linha é tratada como espaço em branco e as linhas são juntadas; tem de pôr dois espaços finais no fim da linha, ou usar uma barra invertida, dependendo do parser. CommonMark permite ambos. Alguns parsers mais antigos exigem um <br> explícito.
7. Markdown e HTML misturados. O Markdown foi concebido para deixar passar HTML arbitrário, por isso largar um <div class="callout"> num ficheiro Markdown funciona. Mas no momento em que põe sintaxe Markdown dentro de um bloco HTML, os parsers divergem: CommonMark trata a maioria dos blocos HTML como opacos; Markdown Extra introduziu markdown="1" para optar por parsing aninhado.
8. Entidades HTML e escapes de caracteres. Um e comercial & num URL não precisa de escape dentro de um link Markdown, mas o mesmo & fora de um link será passado a HTML e pode precisar de ser & para conformidade estrita HTML5. A maioria dos renderizadores lida com isto automaticamente; alguns não.
9. IDs de cabeçalho. O GitHub auto-gera IDs de fragmento de URL a partir do texto do cabeçalho usando uma regra de slugify; muitos parsers fazem o mesmo, mas os algoritmos de slugify diferem. Mesmo cabeçalho, âncora diferente entre plataformas, uma causa perene de links intra-documento partidos quando o conteúdo se move entre sistemas.
10. Espaços finais e definições do editor. Editores que removem espaços finais ao guardar apagarão silenciosamente a sintaxe de quebra de linha de dois espaços finais do Markdown. Editores que convertem tabs em espaços (ou o contrário) partirão blocos de código que dependem de indentação.

Markdown e segurança, XSS e sanitização

Markdown é perigoso de uma forma específica: cada parser convencional passa HTML cru sem alteração. Isso é por design (é o que torna o Markdown útil para callouts e embeds escritos à mão) mas também significa que um previewer Markdown que injecta a saída do parser directamente no DOM é, por defeito, um vector XSS. Colar <img src=x onerror="alert(1)"> num editor Markdown e renderizar a saída sem sanitização executará o alerta. Duas camadas de defesa são padrão. Primeiro, configuração ao nível do parser: marked.js, markdown-it e remark expõem opções para desactivar HTML cru ou escapá-lo na saída (markdown-it tem html: false por defeito; remark/rehype tem rehype-sanitize). GFM especifica adicionalmente a extensão «HTML cru proibido» que remove uma lista fixa de elementos perigosos. Segundo e mais robusto, sanitização HTML após o parsing: DOMPurify, escrito pela firma de segurança berlinense Cure53 a partir de Fevereiro de 2014, é o sanitizer JavaScript de facto. Aceita uma string HTML, faz parse num DOM, percorre a árvore permitindo apenas um subconjunto seguro e configurável de elementos e atributos, e serializa o resultado. DOMPurify remove <script>, bloqueia handlers de eventos inline, retira URLs javascript:, e lida com cem bypasses XSS subtis (abusos de SVG <use>, polyglots de atributos MathML) que um sanitizer regex ingénuo perderia. O pipeline recomendado para qualquer previewer baseado em navegador que aceite HTML cru é: markdownString → parser → htmlString → DOMPurify.sanitize() → innerHTML. CommonMark também exige explicitamente que os parsers recusem URIs javascript: em autolinks; a maioria dos parsers estende essa rejeição a todas as formas de link.

Markdown vs reStructuredText vs AsciiDoc

Markdown é a linguagem de marcação leve dominante mas não a única. reStructuredText (reST) foi lançado pela primeira vez em Junho de 2001 por David Goodger como parte do Python Doc-SIG, evoluindo a partir de um formato Zope anterior chamado StructuredText. Tornou-se o formato de documentação oficial do Python em 2002 e é a linguagem de entrada para o Sphinx, o gerador de documentação por trás de quase todos os docs de projectos Python (os docs oficiais da linguagem Python, NumPy, SciPy, Django, Flask, scikit-learn, pandas, a documentação do kernel Linux desde 2016, CMake, LLVM). A filosofia de design do RST é essencialmente o oposto da do Markdown: aceita mais ruído visual na fonte em troca de mais precisão semântica na saída. RST tem um mecanismo de extensão incorporado via «directivas» (.. note::, .. code-block:: python) e «papéis» (:func:, :ref:) que permite a um projecto definir marcação específica do domínio sem deixar o formato. AsciiDoc foi criado em 2002 por Stuart Rackham como uma ferramenta Python que deliberadamente visa a semântica DocBook XML (cada documento AsciiDoc mapeia limpamente para DocBook) fazendo dele a marcação de eleição para projectos que precisam de livros de qualidade de publicação, especificações técnicas e manuais. AsciiDoc é em que está escrita a documentação do projecto Git, o que a O’Reilly Media usa para muitos dos seus livros, o que a Red Hat e a Mozilla usam para vários conjuntos de documentação de produto, e o que o GitHub e GitLab suportam nativamente como alternativa a README.adoc. A implementação Python original foi substituída pelo Asciidoctor, uma implementação Ruby lançada em 2013. Orientação prática: escolha Markdown para posts de blog, READMEs, chat, notas e a maior parte da documentação; reStructuredText para documentação Python processada pelo Sphinx; AsciiDoc para livros longos ou especificações que precisem de renderizar para DocBook, PDF e EPUB simultaneamente com fidelidade semântica completa.

Perguntas Frequentes

Quais recursos do Markdown são suportados?

Este visualizador suporta títulos, negrito, itálico, links, imagens, listas, citações, blocos de código, tabelas, linhas horizontais e tachado. Cobre a especificação CommonMark e extensões comuns.

Posso exportar o HTML renderizado?

Você pode copiar a saída renderizada do painel de prévia. Para o HTML bruto, clique com o botão direito na prévia e use os recursos "Inspecionar" ou "Ver código-fonte" do seu navegador para copiar a marcação gerada.

Meu texto é salvo?

Não. Tudo roda no seu navegador e nada é armazenado ou enviado a um servidor. Feche a aba e seu texto desaparece. Copie seu Markdown antes de sair se quiser salvá-lo.

O meu texto é guardado ou enviado para algum lugar?

Não. O parser Markdown corre inteiramente no seu navegador via JavaScript. Nada é carregado, nenhuma API é chamada, nenhum log é escrito. Feche o separador e o texto desaparece. Se quiser guardar o que escreveu, copie-o antes de sair da página. Pode também usar a página offline depois de ter sido carregada uma vez, o cache via service-worker significa que o parser permanece disponível sem ligação à internet.

O previewer sanitiza HTML cru?

O parser passa HTML cru, o que é o comportamento CommonMark padrão, útil para incrustar um ocasional <div> ou <details>. Como a entrada vem da sua própria sessão de navegador e a saída só é renderizada no seu próprio separador, isto é seguro para o caso de uso de preview de uma pessoa para o qual foi construído. Se estiver a publicar a saída num sistema multi-utilizador (um CMS, um fórum, um site de documentação que aceita submissões de utilizadores) deve sempre passar o HTML renderizado por um sanitizer como DOMPurify antes de o injectar numa página pública, Markdown mais HTML cru é um vector XSS em qualquer sistema onde o autor e o leitor são pessoas diferentes.

Há limites no tamanho de ficheiro?

Sem limite rígido. O parser lida com dezenas de milhares de linhas de Markdown sem problema num laptop típico. O re-render ao vivo corre em cada toque de tecla, por isso documentos muito grandes (um livro inteiro num só ficheiro) começarão a parecer lentos em dispositivos mais lentos. Dividir em capítulos, ou colar conteúdo para renderizar uma vez e depois editar offline, é a solução. A página não congelará o seu navegador, marked.js é um dos parsers Markdown mais rápidos disponíveis.

Ferramentas relacionadas