Escrevo Markdown todos os dias úteis durante anos - plugin READMEs, changelogs, docs for Toolz.dev, notas de versão do WP Adminhy, metade das minhas mensagens de commit. E na maior parte desse tempo eu tratei a etapa de renderização como mágica. Você escreve asteriscos, o GitHub mostra ousado. Bem. Siga em frente.
Em seguida, construí uma seção do Documentos que retirou o Markdown do banco de dados e a transformei em uma página do Next.js, e o Magic se transformou em uma lista de decisões muito específicas que eu tive que tomar. Uma única nova linha se torna um <br>? (Os comentários do GitHub dizem que sim. A especificação de remarcação diz que não.) faz <div> Na fonte renderizada como um div ou como texto literal? (Depende de quem está perguntando e se você confia no autor.) Qual classe vai em um bloco de código cercado para que o marcador o pegue? Por que um analisador gira **bold**text em negrito e outro deixa isso sozinho?
Nada disso é exótico. É apenas o que ninguém lhe conta, porque Markdown parece tão simples que as pessoas assumem que não há nada por baixo disso. Há bastante sob ele. o Remarcação para HTML O conversor no Toolz.dev expõe essas decisões como interruptores em vez de ocultá-las, que é a versão dessa ferramenta que eu queria quando estava depurando por que minhas quebras de linha continuaram desaparecendo.
tl;dr: Markdown é um formato de escrita; HTML é o formato de exibição Algo tem que compilar um no outro As regras que fazem as pessoas subirem: linhas consecutivas se juntam em um parágrafo, a menos que você termine uma linha com dois espaços (ou ative um & quot; breaks" opção), HTML bruto é passado ou escapou dependendo do analisador & #39; s confie nas configurações e o dialeto GitHub & #39; s (GFM) adiciona tabelas, listas de tarefas, strikethrough e autolinking bare-URL em cima do ponto comum linha de base. Código cercado compila para
<pre><code class="language-js">, que é o prisma do gancho, destacam.js e shiki procuram. o Conversor de marcação para HTML Faz tudo isso no seu navegador, com cada interruptor exposto.
O que é Markdown e por que ele precisa ser convertido?
Markdown é uma sintaxe de texto simples que John Gruber publicou em 2004, com um objetivo de design declarado: um documento Markdown deve ser publicável como está, legível como texto simples, sem parecer que foi marcado com tags É por isso que a sintaxe toma emprestado das convenções que as pessoas já usavam no e-mail - asteriscos em torno de uma palavra para ênfase, uma linha de traços sob um título, a > para uma cotação.
A consequência é que o Markdown não é um formato de renderização. Nada exibe Markdown. Os navegadores exibem HTML e todos os lugares que você já visto Markdown renderizado - GitHub, um site estático, um portal docs, um aplicativo de bate-papo - executou um analisador primeiro e colocou HTML na tela.
Portanto, a conversão deve acontecer em algum lugar. Suas opções são aproximadamente:
- Na hora da construção, em um gerador de site estático ou empacotador. Tudo bem quando o conteúdo estiver em seu repositório.
- A hora do pedido, em um servidor. Necessário quando o conteúdo vem de um banco de dados, caro se você fizer isso em todas as solicitações sem armazenar em cache.
- no navegador, no momento em que você precisa. Que é o que você deseja quando a resposta para "Eu só preciso do HTML para essa coisa" é uma cópia-cola, não um pipeline de compilação.
Esse terceiro caso é mais comum do que parece. Colando notas de versão em um campo CMS que recebe apenas HTML. Obtendo um ReadMe em um modelo de e-mail. Verificar como será um documento antes de você comprová-lo. Converter um rascunho escrito em Obsidian em algo que você pode entregar a um designer. Nenhum deles justifica a ligação de um analisador em um projeto.
Qual é a diferença entre CommonMark e Markdown com sabor do GitHub?
A especificação original do Gruber era uma página de prosa e um script Perl, e deixou ambiguidade suficiente para que todas as implementações discordassem nos casos de borda. ponto comum é a resposta para isso: uma especificação rigorosa e testável com um conjunto de conformidade de centenas de exemplos, de modo que dois analisadores em conformidade produzam saída idêntica para a mesma entrada Ele define a linha de base - títulos, parágrafos, ênfase, links, imagens, listas, blockquotes, blocos de código, quebras temáticas, escapes de barra invertida, blocos HTML.
Markdown com sabor do GitHub (GFM) É um superconjunto formal do CommonMark, especificado pelo GitHub, que adiciona as coisas que as pessoas continuaram pedindo:
| característica | ponto comum | GFM | sintaxe |
|---|---|---|---|
| mesas | não | sim | | a | b | com um | --- | --- | linha delimitadora |
| Listas de tarefas | não | sim | - [x] done / - [ ] todo |
| tacanete | não | sim | ~~gone~~ |
| URLs simples vinculados automaticamente | não | sim | https://toolz.dev sem suportes |
| notas de rodapé | não | Sim (extensão do GitHub) | [^1] |
| Títulos, listas, código, ênfase | sim | sim | idêntico |
Se sua rebaixamento veio de um Readme do GitHub, de um wiki do Gitlab, de uma exportação de noção ou da maioria dos editores modernos, é o GFM. Ativar o GFM no conversor ou suas tabelas serão renderizadas como tubos literais, que é o número um, pergunta de suporte que qualquer um que enviar uma dessas ferramentas recebe.
Por que minha quebra de linha desapareceu?
Porque o Markdown, seguindo as convenções do e-mail em texto simples, trata as linhas não em branco consecutivas como um único parágrafo. isto:
Line one
Line two
produz <p>Line one\nLine two</p>- um parágrafo, e a nova linha colapsa para um espaço quando o navegador o renderiza Não é um bug; é a especificação, e ela existe para que você possa embrulhar sua prosa em 80 colunas em um editor de texto sem que esse invólucro vaze para a saída.
Existem três maneiras de obter uma pausa real:
- uma linha em branco Inicia um novo parágrafo. É isso que você deseja na maioria das vezes.
- Dois espaços à direita no final de uma linha produzir uma pausa difícil -
<br />. Este é o truque padrão e é invisível em seu editor, e é por isso que as pessoas acham isso enlouquecedor. - uma barra invertida No final da linha faz o mesmo no CommonMark e é pelo menos visível.
E então há a quarta maneira, que é a fonte da confusão: Muitas plataformas ativam um modo "quebras" Onde cada nova linha se torna um <br />. Comentários e questões do GitHub fazem isso. A maioria dos aplicativos de bate-papo faz isso. Arquivos de leitura do GitHub não. Portanto, o mesmo texto é renderizado de forma diferente em um problema do GitHub e no readme do mesmo repositório, que é uma peça genuinamente ruim com o qual todos nós estamos presos.
O conversor expõe isso como um interruptor. Se sua fonte foi escrita para um renderizador no estilo de bate-papo, ative as quebras de linha. Se for um documento, deixe-o desligado e use linhas em branco como a especificação pretende.
Como o HTML bruto é tratado?
Markdown permite HTML inline - a especificação original diz explicitamente qualquer HTML que você escreve passa direto por Isso é um recurso quando você é o autor (você quer o seu <details> bloco, seu <img> Com um atributo de largura, sua âncora com um rel), e é uma responsabilidade quando você não está.
Porque se você renderizar o Markdown não confiável com a passagem HTML ativada, você terá uma vulnerabilidade XSS. <script>alert(document.cookie)</script> é válido remarcação. assim é <img src=x onerror="...">. Então é um <a href="javascript:...">. Uma caixa de comentários, uma biografia do perfil do usuário, um wiki público - em qualquer lugar onde estranhos escrevam Markdown que outras pessoas leem - devem escapar do HTML ou higienizar a saída com um desinfetante real (DOMPurify é a resposta usual, e é um desinfetante real precisamente porque um regex não é suficiente para uma entrada hostil).
Este conversor padroniza fuga HTML bruto: <div> em sua fonte aparece como o texto literal <div> Na saída, exatamente como se você tivesse escrito <div>. Você pode ativar o repasse quando a fonte é sua. E independentemente dessa configuração, as faixas de visualização ao vivo <script>, <style>, embutido on* manipuladores de eventos e javascript: URLs antes de renderizar - uma medida de defesa em profundidade, então colar outra pessoa e #39; O README no painel de visualização não pode executar seu código. Essa é uma medida de segurança de visualização, não um desinfetante de uso geral: se você estiver construindo um produto que renderiza o Markdown do usuário, use um servidor desinfetante dedicado e não confie em um regex, incluindo o meu.
Se você precisa escapar de um personagem desde Marque para renderizar literalmente - um asterisco que deve permanecer um asterisco, um sublinhado em um nome de arquivo - uma barra invertida faz isso: \*not emphasis\*. E se você estiver disputando entidades na outra direção, o Encoder/decodificador de entidades HTML é a ferramenta para esse trabalho.
Qual HTML um bom conversor deve realmente emiter?
HTML semântico, chato e sem classes - com uma exceção.
- Os títulos se tornam
<h1>–<h6>. Com os IDs de cabeçalho ativados, cada um também recebe um Slugfiedid, desduplicado quando dois títulos compartilham um título (#setup,#setup-1). é isso que faz#anchorOs links diretos funcionam e é o que um gerador de conteúdos trava. - Um bloco cercado com uma string de informações -
```js- torna-se<pre><code class="language-js">. *Esta é a exceção.* * A linguagem-` class é o prisma da convenção, o destaque.js e o shiki procuram, e é por isso que o conversor emite uma classe. O conversor não colore o seu código; o marcador da sua página sim, e precisa desse gancho. - As listas se tornam
<ul>/<ol>, e aqui está uma sutileza que vale a pena saber: um apertado List (sem linhas em branco entre os itens) coloca o texto diretamente dentro<li>, enquanto um afrouxa List (linhas em branco entre os itens) envolve o conteúdo de cada item em<p>. Esse é o comportamento Commonmark, não uma peculiaridade, e é por isso que sua lista aumenta o espaçamento vertical de repente quando você adiciona uma linha em branco entre duas balas. O CSS não está quebrado; o HTML foi alterado genuinamente. - As tabelas se tornam reais
<table>/<thead>/<tbody>marcação, comstyle="text-align:center"Em células quando a linha delimitadora usa:---:. - As listas de tarefas se tornam
<input type="checkbox" disabled>Dentro do<li>, que é exatamente o que o GitHub emite.
Content-First, sem wrapper divs, sem classes de utilidades. Você o estiliza do lado de fora, com um .prose classe ou suas próprias regras, e a marcação permanece portátil.
Como uso o conversor?
Etapa 1: colar o markdown
Coloque um README, um changelog, notas de lançamento, um rascunho Atualizações de saída conforme você digita - não há botão de conversão e nada é carregado.
Etapa 2: defina os interruptores
Com sabor de GitHub ON se a fonte tiver tabelas, listas de tarefas ou tachas (provavelmente tem). IDs de cabeçalho ON se você quiser âncoras. quebras de linha Ativado somente se a origem foi escrita para um renderizador no estilo de bate-papo. Permitir HTML bruto Ativado somente se a fonte for sua. documento completo em Se você deseja uma página completa do HTML5 com Doctype, Charset, Viewport e um <title> tirado do seu primeiro <h1>- útil quando você deseja abrir o resultado diretamente em um navegador ou soltá-lo em um host estático.
Passo 3: verifique a visualização
Mude para a guia de visualização e confirme a estrutura A linha de estatísticas informa palavras, títulos, links, imagens, blocos de código e tempo de leitura - útil para verificar uma postagem é o comprimento que você pensou que era antes de publicá-la Para uma contagem mais completa, o contador de palavras Faz legibilidade e densidade de palavras-chave no mesmo texto.
Etapa 4: pegue a saída
Copie o HTML, baixe-o como um .html arquive ou copie o índice gerado - uma lista aninhada Markdown vinculada a cada âncora de título, pronta para colar novamente na parte superior do seu documento.
Se você estiver cosando o resultado em uma página onde os bytes são importantes, execute-o através do Minificador de HTML depois. A saída do conversor é recuada para legibilidade, não para o fio.
Casos de uso comuns
Obtendo um Leiame em um site
Os autores de plug-ins e pacotes escrevem um bom leia-me e, em seguida, precisam do mesmo conteúdo em uma página de destino. O Readme é GFM com tabelas e distintivos; a página de destino precisa de HTML. Converta, cole, estilize com seu CSS existente. Os IDs de título oferecem uma barra lateral gratuitamente.
Publicar em um CMS que aceita apenas HTML
Muitos campos CMS, plataformas de e-mail e painéis de administração legados levam HTML e nada mais Se você redigir no Markdown - e a maioria das pessoas que escrevem regularmente o fazem - esta é a ponte Converter com documento completo Desativado, você obtém o fragmento em vez de uma página inteira e colá-lo no campo.
Prototipagem de uma página do Documentos
Antes de confirmar o conteúdo em um site do Documentos, convertê-lo localmente mostra a hierarquia de títulos reais e se suas cercas de código têm o idioma certo. um h3 Isso deveria ter sido um h2 é óbvio no TOC e invisível na fonte.
Auditando o conteúdo de outra pessoa escreveu
Cole um contribuidor' s Markdown, olhe para o HTML emitido, e você pode ver imediatamente se eles usaram títulos reais ou negrito uma linha para falsificar um - um hábito que destrói a estrutura do documento e acessibilidade Os leitores de tela navegam por cabeçalho; **Big Text** Não é um título, é um parágrafo em negrito e o conversor mostra isso em uma linha de saída.
Extraindo um índice
Os documentos longos precisam de um, e mantê-lo manualmente garante que ele fica obsoleto. Gere-o a partir dos títulos, cole-o, regenere-se sempre que os títulos forem alterados.
Avançado: o que este analisador faz e não faz
É um analisador escrito à mão, com cerca de 400 linhas, sem dependências - o que é deliberado, porque um analisador Markdown que puxa uma dependência de 200 KB para uma página cujo ponto inteiro é ser rápido é uma negociação ruim.
coberto: Títulos ATX (# x) e títulos SeText (sublinhados com === / ---), parágrafos, ênfase e forte (*, _, **, __), código embutido com backtick-run, código cercado com informações, blocos de código, blocos de blocos com preguiçosos, listas aninhadas (ordenadas e não ordenadas, apertadas e soltas), quebras temáticas, links e imagens com títulos, links automáticos de suporte angular, links automáticos de e-mail, escapamentos de barra invertidas e o conjunto GFM: tabelas com alinhamento, listas de tarefas, retaliação, tapa-arroamento.
Não coberto: Links do estilo de referência ([text][ref] com um [ref]: url Definição em outro lugar), notas de rodapé, listas de definição e alguns casos de canto comum genuinamente obscuros em torno de blocos HTML que interrompem parágrafos. Se você estiver executando o Commonmark Conformance Suite em relação a ele, ele não terá pontuação 100%. Se você estiver convertendo um ReadMe, um Changelog ou um post de blog, você não notará.
Essa é uma troca honesta e é a razão pela qual o conversor carrega instantaneamente e funciona com a rede desligada. Para pipelines de conteúdo onde você precisa de uma conformidade de marca comum exata, use markdown-it, remark ou cmark em sua construção; é para isso que servem.
FAQ
Como faço para converter markdown em HTML?
Cole seu Markdown no editor e o HTML aparecerá imediatamente - não há botão de conversão e nenhum arquivo para fazer upload Ative o GitHub Flavored Markdown se sua fonte usar tabelas ou listas de tarefas, então copie o HTML ou baixe-o como um arquivo.html Tudo é executado em seu navegador, então rascunhos não publicados e documentos internos nunca saem do seu dispositivo.
O que é o Markdown com sabor do GitHub?
O Markdown com sabor do GitHub (GFM) é um superconjunto formalmente especificado de Commonmark que adiciona tabelas, caixas de seleção de lista de tarefas, tachas com tils duplos e links automáticos de URLs nus. É o dialeto que o GitHub usa para renderizar arquivos e problemas do Readme, e é o que a maioria dos editores de remarcação emite hoje. Ele é ativado por padrão neste conversor.
Por que minha quebra de linha única desapareceu?
Padrão Markdown une linhas consecutivas em um único parágrafo; uma quebra de linha sobrevive apenas se você terminar a linha com dois espaços, usar uma barra invertida ou deixar uma linha em branco. Se você deseja que todas as novas linhas se tornem uma <br />, habilite a opção de quebra de linha - esse é o comportamento que os comentários do GitHub e a maioria dos aplicativos de bate-papo usam, mas não é o que os arquivos README fazem.
O conversor destaca meu código?
Ele emite a marcação que um marcador precisa, mas não colore o código em si. um bloco de código cercado marcado com o idioma js torna-se <pre><code class="language-js">, que é o prisma da convenção da classe, realce.js e shiki procuram. Adicione uma dessas bibliotecas à página onde você cola a saída e o realce aparece automaticamente.
O HTML bruto dentro do meu Markdown está preservado?
Por padrão, ele é escapado, então <div> aparece como texto literal em vez de uma tag. Ative a opção permitir que o HTML bruto passe tags diretamente, que é o que você deseja quando seu Markdown mixa deliberadamente em HTML - a <details> bloco ou uma imagem com atributos. Ative-o apenas para a fonte de sua confiança, porque o HTML bruto de um autor não confiável é um vetor XSS.
É seguro colar Markdown que não escrevi?
Sim. HTML é escapado por padrão, e a visualização ao vivo adicionalmente retira tags de script e estilo, manipuladores de eventos inline e javascript: URLs antes da renderização Nada do que você colar é transmitido em qualquer lugar Se você estiver construindo um produto que renderiza Markdown de estranhos, ainda use um desinfetante dedicado, como o lado do servidor do DOMPurify - um filtro de visualização não substitui um.
Posso gerar um sumário de meus títulos?
Sim. Com os IDs de títulos ativados, cada título recebe uma âncora de duplicação esqueleto e a ferramenta cria um índice de remarcação com links para cada um. Copie-o de volta para o topo do documento e os links serão resolvidos em relação aos IDs gerados. Regenere-o sempre que seus títulos forem alterados, em vez de mantê-lo manualmente.
Este conversor implementa totalmente o CommonMark?
Ele implementa as construções que as pessoas realmente escrevem - títulos ATX e setext, parágrafos, ênfase, links, imagens, autolinks, blockquotes, listas aninhadas e soltas, código cercado e recuado, quebras temáticas, escapes de barra invertida - além das extensões GFM. Links de estilo de referência, notas de rodapé e alguns casos raros de borda de bloco HTML CommonMark não são cobertos Para conformidade bit-exato em um pipeline de construção, use markdown-it, remark ou cmark.
Ferramentas relacionadas: Remarcação para HTML · entidades html · Minificador de HTML · contador de palavras · gerador de slug
Leitura relacionada: O kit de ferramentas do desenvolvedor web · Guia de ferramentas de texto
