Anteprima Markdown gratuita online

Riferimento rapido Markdown

Informazioni su Markdown

Markdown fu creato da John Gruber, lo scrittore dietro al weblog Daring Fireball, con un sostanziale feedback di design da Aaron Swartz. La prima release pubblica, versione 1.0, fu annunciata sul sito di Gruber il 9 marzo 2004; la versione 1.0.1, la release di riferimento canonica, seguì il 17 dicembre 2004 ed è ancora la versione collegata da daringfireball.net/projects/markdown. Markdown è due cose insieme: una sintassi di formattazione in testo semplice e lo script Perl originale che converte quella sintassi in HTML. L'obiettivo dichiarato di Gruber era che il testo sorgente fosse leggibile così com'è: un documento Markdown aperto in un editor di testo semplice doveva sembrare un'email formattata con cura, non una zuppa di tag. Quel vincolo di leggibilità è la linea filosofica che separa Markdown dai formati basati su XML e da markup più pesanti come LaTeX, ed è il motivo per cui ogni estensione successiva ha dovuto giustificarsi in termini di quanto malamente disturbasse la sorgente.

Gruber accredita ampiamente Swartz nei riconoscimenti di Markdown: "Aaron Swartz merita una quantità tremenda di credito per il suo feedback sul design della sintassi di formattazione di Markdown." Swartz aveva precedentemente scritto un markup leggero correlato chiamato atx (2002), che ha contribuito allo stile di intestazioni con # e ## ora familiare, talvolta ancora chiamato "atx-style headings" all'interno delle specifiche dei parser. Il coinvolgimento di Swartz è un pezzo della sua eredità più ampia: ha co-costruito RSS 1.0 da adolescente, è stato co-proprietario di Reddit fino al 2007 e ha continuato a influenzare gli standard del web aperto fino alla sua morte nel 2013. Una curiosità che vale la pena di chiarire: l'estensione di file .md è ora quasi universale, ma lo strumento originale di Gruber usava .text: la migrazione a .md è stata una convenzione della comunità che ha preso piede una volta che Markdown ha lasciato la nicchia del blogging.

Perché Markdown ha vinto sul web

Un linguaggio di markup vince essendo adottato dalle piattaforme che pubblicano la maggior parte del testo del mondo. In una stretta finestra di cinque anni, Markdown è stato adottato dalle piattaforme che sono giunte a dominare la discussione long-form, la collaborazione sul codice e la documentazione per sviluppatori. Stack Overflow è stato lanciato il 15 settembre 2008 con Markdown come sintassi di formattazione per domande, risposte e commenti, usando un editor chiamato WMD (Wysiwym Markdown) di John Fraser di AttackLab; il team di Stack Overflow lo ha poi riscritto come l'editor open-source PageDown mantenuto su github.com/StackExchange/pagedown. Reddit, fondato da Steve Huffman e Alexis Ohanian nel 2005 con Aaron Swartz unitosi poco dopo, ha distribuito Markdown per i commenti non molto dopo il lancio e ha portato la sintassi a un pubblico molto più ampio e non da sviluppatori. GitHub è stato lanciato nel 2008 e nel giro di un anno stava renderizzando Markdown nei README.md e nei commenti delle issue; nel 2009 ha cominciato a documentare e distribuire il proprio dialetto, GitHub Flavored Markdown. Discord, lanciato a maggio 2015, ha adottato una sintassi chat con sapore Markdown per grassetto, corsivo, barrato, codice inline, code fence e blockquote: ciò che la maggior parte dei non sviluppatori sotto i 25 anni ora pensa come "mettere asterischi attorno a qualcosa." L'abilità si compone: uno scrittore che impara Markdown una volta può scrivere post di blog in Jekyll/Hugo/Eleventy, documentazione in MkDocs/Docusaurus/Read the Docs, presentazioni in Marp e Reveal.js, appunti in Obsidian/Bear/Logseq/Notion, chat in Slack e Discord e documentazione del codice sorgente in essenzialmente ogni progetto open-source moderno.

CommonMark: correggere la sotto-specificazione

La descrizione di sintassi originale di Gruber del 2004 era notoriamente informale: un documento in prosa con esempi, non una grammatica. Lasciava decine di casi limite non specificati ("come interagisce l'enfasi con gli underscore in mezzo a una parola?"; "una lista dentro un blockquote chiude il blockquote?"; "cosa conta come tight versus loose list?") e Gruber non ha mai rilasciato un parser di riferimento diverso dal suo script Perl, il cui comportamento era idiosincratico in modi che gli altri implementatori dovevano o copiare o sovrascrivere. Il risultato all'inizio degli anni 2010 era che GitHub, Reddit, Stack Overflow, Pandoc e il parser C Discount renderizzavano tutti la stessa sorgente Markdown leggermente diversa, e lo stesso input poteva rompersi tra le piattaforme.

Nel 2012, il co-fondatore di Stack Overflow Jeff Atwood (a quel punto al timone di Discourse) e l'autore di Pandoc John MacFarlane iniziarono uno sforzo per scrivere una specifica reale e testabile. Furono raggiunti da David Greenspan (Meteor), Vicent Marti (GitHub), Neil Williams (Reddit) e Benjamin Dumke-von der Ehe (Stack Exchange). Il progetto fu lanciato pubblicamente nel settembre 2014 come "Standard Markdown"; nel giro di pochi giorni Gruber obiettò al nome via email privata, Atwood scrisse un post pubblico che spiegava il cambio, e il progetto fu rinominato "CommonMark." La prima release numerata arrivò il 25 ottobre 2014. La versione pubblicata attuale è CommonMark 0.31.2, rilasciata il 28 gennaio 2024: una "1.0" era stata promessa per il 2019 e non è arrivata perché un piccolo numero di casi limite patologici (notabilmente attorno al parsing dell'enfasi e all'embedding di HTML) non hanno prodotto risoluzioni unanimi. In pratica 0.31.2 è trattata come stabile per la produzione. La specifica CommonMark è insolita nel fatto di essere essa stessa un documento CommonMark, con oltre 600 casi di test eseguibili inline; un parser dichiara la conformità superando quei test.

GitHub Flavored Markdown: cinque estensioni in cima

La specifica formale GFM, pubblicata nel 2017 e più recentemente versionata come 0.29-gfm il 6 aprile 2019, definisce cinque estensioni in cima a CommonMark: tabelle (blocchi delimitati da pipe con una riga delimitatrice che usa trattini e : per l'allineamento per colonna); elementi list task (voci di lista che iniziano con [ ] per non spuntato o [x] per spuntato, renderizzati come checkbox HTML disabilitati: GitHub permette inoltre agli utenti loggati di togglarli cliccando, che è uno strato UX in cima alla specifica, non parte della specifica stessa); strikethrough (avvolgere il testo in ~~ produce <del>: CommonMark stesso non specifica questo); estensione autolink (URL nudi e indirizzi email nel testo corrente sono auto-linkati, mentre CommonMark lo fa solo per autolink espliciti tra parentesi angolari); e raw HTML non consentito (una restrizione di sicurezza che elimina <script>, <iframe>, <style>, <title>, <plaintext>, <textarea>, <xmp>, <noembed>, <noframes> e una manciata di altri tag pericolosi). Una sesta funzionalità comunemente attribuita a GFM ma che vale la pena trattare con cura sono i code block fenced con identificatori di linguaggio: i code block fenced sono parte di CommonMark stesso; il suggerimento di linguaggio dopo la fence di apertura è anche CommonMark; l'evidenziazione della sintassi che GitHub poi applica basandosi su quel suggerimento è il comportamento di rendering di GitHub, non la specifica. Il renderer di GitHub esegue anche post-processing aggiuntivo: sanificazione HTML tramite la sua gemma html-pipeline interna, espansione di shortcode emoji (:smile:), autolinking di @user e #issue: nessuno dei quali è in GFM stesso.

I parser principali

marked.js fu creato da Christopher Jeffrey, con copyright originale datato 2011, ed è stato mantenuto dall'organizzazione GitHub markedjs dal 2018. È un design lexer-then-parser a passaggio singolo che dà priorità alla velocità grezza; i documenti lo posizionano esplicitamente come "un compilatore di basso livello per il parsing di markdown senza caching o blocking." È il parser che questo previewer usa attualmente per il render live. Marked è piccolo, veloce, estensibile attraverso hook di token e uno dei progetti markdown più stellati su GitHub (~36k stelle).

markdown-it fu lanciato nel 2014 da Vitaly Puzrin e Alex Kocharin. I due avevano precedentemente contribuito quasi tutto il codice a un parser chiamato Remarkable; quando dispute di leadership bloccarono i progressi riorganizzarono la stessa autorialità attorno a markdown-it. Il progetto pubblicizza il 100% di conformità CommonMark con toggle GFM opzionali per tabelle e strikethrough, più un ecosistema di plugin aggressivo (markdown-it-footnote, markdown-it-emoji, markdown-it-attrs, markdown-it-anchor, markdown-it-task-lists e diverse centinaia di altri). È il parser usato dal preview Markdown integrato di VS Code, dall'UI web di GitLab e da una lunga lista di generatori di siti statici incluso Eleventy.

remark / unified.js non è un singolo parser ma un framework di trasformazione di alberi. Il collettivo unified, partito attorno al 2014, definisce una specifica di abstract syntax tree chiamata mdast (Markdown Abstract Syntax Tree); remark analizza Markdown in mdast, i plugin manipolano l'albero, e remark-rehype converte mdast in hast (l'AST HTML) per l'emissione. Il modello è più lento di marked ma vastamente più componibile. Utenti notabili includono Prettier (che formatta Markdown usando remark), Gatsby, MDN, la pipeline di documentazione di Node.js e il linter di linguaggio inclusivo alex. Il collettivo unified elenca 312 progetti e circa 6,3 miliardi di download mensili da npm su tutti i suoi pacchetti.

MDX, primo commit alla fine del 2017 da John Otander e altri collegati alla compagnia di design tool Compositor, fu annunciato pubblicamente al ZEIT Day 2018 e ha rilasciato 1.0 l'11 aprile 2019. MDX combina contenuto Markdown con componenti JSX, così che uno scrittore può inserire un <Chart /> o <Tweet id="123" /> direttamente nella prosa. Alimenta i docs di Next.js, Docusaurus e la maggior parte dei siti di documentazione basati su React. MDX ha il proprio parser distinto da CommonMark; v1 era basato su remark, v2+ usa una grammatica MDX dedicata per gestire correttamente le espressioni JSX dentro il contesto di paragrafo.

Pandoc: il convertitore universale

Pandoc fu rilasciato da John MacFarlane, allora professore di filosofia alla University of California, Berkeley, il 10 agosto 2006. È scritto in Haskell, e il suo design si centra sul parsing di uno qualunque di circa 30 formati di input (Markdown, reStructuredText, HTML, LaTeX, DocBook, Textile, markup MediaWiki e DokuWiki, Org-mode, Microsoft Word .docx, OpenDocument, EPUB, JATS XML, Jupyter .ipynb e altri) in un modello documentale astratto condiviso, poi rendendo quel modello in circa 40 formati di output (HTML, PDF via LaTeX o wkhtmltopdf, .docx, .odt, ePub2/3, formati di slide inclusi Beamer e reveal.js, e molti altri). È onnipresente nell'editoria accademica e tecnica perché trasporta citazioni attraverso CSL JSON / BibTeX e le risolve in riferimenti formattati per uno qualunque dei principali stili di citazione. Il dialetto Markdown che Pandoc analizza per default ("Pandoc Markdown") è esso stesso un superset di CommonMark con estensioni per note a piè di pagina, definition list, fenced div, matematica (in stile LaTeX $...$ e $$...$$) e didascalie di tabella. Pandoc è licenziato GPL v2-or-later ed è ciò che la maggior parte dei dipartimenti accademici usano per compilare manoscritti Markdown in documenti Word pronti per la rivista.

MultiMarkdown, Markdown Extra e SmartyPants

Due dialetti di estensione precedenti precedono CommonMark e hanno influenzato sia GFM sia Pandoc. MultiMarkdown fu creato da Fletcher T. Penney con un rilascio iniziale a maggio 2007 (il lavoro di progetto cominciò 2005-2006), motivato dalla scrittura accademica: Penney voleva un Markdown capace di produrre un manoscritto pubblicabile con note a piè di pagina, citazioni, matematica, definition list e metadati di documento in stile YAML. MultiMarkdown ha introdotto o popolarizzato le tabelle a carattere pipe, i marcatori di note a piè di pagina [^id], la notazione matematica, i blocchi di metadati a livello di documento all'inizio dei file, e le didascalie di immagini e tabelle. Markdown Extra fu creato da Michel Fortin (autore di PHP Markdown) nel 2005-2006 e aggiunse tabelle pipe, code block fenced con ~~~ (poi anche ```), note a piè di pagina, definition list, abbreviazioni e la sintassi di attributo {#id .class} per le intestazioni. Il suo contributo più distintivo fu il rilassamento delle regole Markdown-dentro-HTML: l'attributo markdown="1" che ti permette di annidare Markdown dentro un blocco HTML. Diverse scelte di design CommonMark e GFM attorno a code fenced e tabelle risalgono a Markdown Extra. Separatamente, SmartyPants, il companion tipografico di Gruber del 2002, esegue sostituzioni tipografiche: virgolette ASCII dritte diventano virgolette curve, doppi e tripli trattini diventano en-dash ed em-dash, tre punti diventano un vero punto puntini di sospensione. Markdown gestisce la struttura; SmartyPants gestisce la rifinitura; molti parser includono comportamento in stile SmartyPants come passaggio di post-processing (markdown-it-smartypants, remark-smartypants), e Pandoc lo ha integrato dietro una flag --smart.

Trabocchetti comuni: dieci cose che mordono i nuovi scrittori

Un previewer live rende immediatamente ovvie la maggior parte delle sorprese di parsing, ma capire perché succedono aiuta uno scrittore a fare la sorgente giusta al primo colpo.

1. Conversione di virgolette intelligenti che rompe gli esempi di codice. I filtri in stile SmartyPants convertono allegramente le virgolette dentro ciò che sembra prosa, incluso, talvolta, dentro span di codice inline o valori di attributi HTML, lasciandoti con markup rotto. La maggior parte dei parser moderni esclude gli span di codice dalla sostituzione tipografica, ma le piattaforme di blog con pipeline custom spesso no.
2. Il rilevamento dei marker di lista è sensibile allo spazio bianco. Mescolare -, * e + dentro la stessa lista, indentare i paragrafi di continuazione di lista di meno di quanto richieda il marker, o mettere una riga vuota tra elementi di lista può capovolgere una tight list in una loose list (ogni elemento avvolto in tag <p>): una differenza invisibile nella sorgente ma drammatica nell'output.
3. Eccesso di zelo dell'autolink. L'autolinking in stile GFM trasforma qualsiasi URL nudo in un link, che è di solito ciò che vuoi, ma può anche rovinare URL dentro ciò che doveva essere uno span di codice, o URL contenenti parentesi (specialmente URL di Wikipedia). La regola per "dove finisce questo URL?" varia tra i parser.
4. Suggerimenti di linguaggio per code fence. Il testo dopo il triplo backtick di apertura (```js contro ```javascript contro ```ts contro ```typescript) è un suggerimento, non una specifica. Diversi syntax highlighter riconoscono diversi alias; Highlight.js, Prism, Shiki e il renderer di GitHub hanno ognuno i propri dizionari di linguaggio.
5. Tabelle che hanno bisogno di escaping. I caratteri pipe dentro le celle di tabella devono essere escapati come \|, altrimenti vengono letti come separatori di colonna. Cattura chiunque cerchi di mettere un esempio di codice di una riga dentro una cella di tabella.
6. Interruzioni di riga forzate. Dentro un paragrafo, un singolo a-capo è trattato come spazio bianco e le righe sono unite; devi mettere due spazi finali alla fine della riga, o usare un backslash, a seconda del parser. CommonMark permette entrambi. Alcuni parser più vecchi richiedono un esplicito <br>.
7. Markdown e HTML mescolati. Markdown è stato progettato per far passare HTML arbitrario, quindi inserire un <div class="callout"> in un file Markdown funziona. Ma nel momento in cui metti la sintassi Markdown dentro un blocco HTML, i parser divergono: CommonMark tratta la maggior parte dei blocchi HTML come opachi; Markdown Extra ha introdotto markdown="1" per optare al parsing annidato.
8. Entità HTML ed escape di caratteri. Una e commerciale & in un URL non ha bisogno di escape dentro un link Markdown, ma la stessa & fuori da un link sarà passata all'HTML e potrebbe aver bisogno di essere & per la stretta conformità HTML5. La maggior parte dei renderer gestisce questo automaticamente; alcuni no.
9. ID delle intestazioni. GitHub auto-genera ID di frammento URL dal testo dell'intestazione usando una regola di slugify; molti parser lo fanno anche, ma gli algoritmi di slugify differiscono. Stessa intestazione, ancore diverse tra le piattaforme: una causa perenne di link intra-documento rotti quando il contenuto si sposta tra sistemi.
10. Spazio bianco finale e impostazioni dell'editor. Editor che eliminano lo spazio bianco finale al salvataggio cancelleranno silenziosamente la sintassi di interruzione di riga a due spazi finali di Markdown. Editor che convertono tab in spazi (o il contrario) romperanno i code block che dipendono dall'indentazione.

Markdown e sicurezza: XSS e sanificazione

Markdown è pericoloso in un modo specifico: ogni parser mainstream fa passare HTML grezzo immutato. Questo è per design (è ciò che rende Markdown utile per callout ed embed scritti a mano) ma significa anche che un previewer Markdown che inietta l'output del parser direttamente nel DOM è, di default, un vettore XSS. Incollare <img src=x onerror="alert(1)"> in un editor Markdown e renderizzare l'output senza sanificazione eseguirà l'alert. Due livelli di difesa sono standard. Primo, configurazione a livello di parser: marked.js, markdown-it e remark espongono tutti opzioni per disabilitare l'HTML grezzo o esciparlo in output (markdown-it ha html: false di default; remark/rehype ha rehype-sanitize). GFM specifica inoltre l'estensione "raw HTML non consentito" che elimina un elenco hardcoded di elementi pericolosi. Secondo e più robusto, sanificazione HTML dopo il parsing: DOMPurify, scritto dalla società di sicurezza berlinese Cure53 a partire dal febbraio 2014, è il sanificatore JavaScript de facto. Prende una stringa HTML, la analizza in un DOM, percorre l'albero permettendo solo un sottoinsieme sicuro configurabile di elementi e attributi, e serializza il risultato. DOMPurify rimuove <script>, blocca gli event handler inline, elimina gli URL javascript: e gestisce un centinaio di sottili bypass XSS (abusi di <use> SVG, poliglotti di attributi MathML) che un sanificatore regex ingenuo mancherà. La pipeline raccomandata per qualsiasi previewer basato su browser che accetti HTML grezzo è: markdownString → parser → htmlString → DOMPurify.sanitize() → innerHTML. CommonMark richiede inoltre esplicitamente che i parser rifiutino gli URI javascript: negli autolink; la maggior parte dei parser estende quel rifiuto a tutte le forme di link.

Markdown contro reStructuredText contro AsciiDoc

Markdown è il linguaggio di markup leggero dominante ma non l'unico. reStructuredText (reST) fu rilasciato per la prima volta nel giugno 2001 da David Goodger come parte del Python Doc-SIG, evolvendosi da un formato Zope precedente chiamato StructuredText. Divenne il formato di documentazione ufficiale di Python nel 2002 ed è il linguaggio di input per Sphinx, il generatore di documentazione dietro a quasi tutta la documentazione dei progetti Python (i docs ufficiali del linguaggio Python, NumPy, SciPy, Django, Flask, scikit-learn, pandas, la documentazione del kernel Linux dal 2016, CMake, LLVM). La filosofia di design di RST è essenzialmente l'opposto di Markdown: accetta più rumore visivo nella sorgente in cambio di più precisione semantica nell'output. RST ha un meccanismo di estensione integrato tramite "direttive" (.. note::, .. code-block:: python) e "ruoli" (:func:, :ref:) che permettono a un progetto di definire markup specifico del dominio senza lasciare il formato. AsciiDoc fu creato nel 2002 da Stuart Rackham come strumento Python che mira deliberatamente alla semantica DocBook XML: ogni documento AsciiDoc si mappa in modo pulito a DocBook, rendendolo il markup di scelta per progetti che hanno bisogno di libri di qualità per la pubblicazione, specifiche tecniche e manuali. AsciiDoc è ciò in cui è scritta la documentazione del progetto Git, ciò che O'Reilly Media usa per molti dei suoi libri, ciò che Red Hat e Mozilla usano per diversi set di documentazione di prodotto, e ciò che GitHub e GitLab supportano nativamente come alternativa README.adoc. L'implementazione Python originale è stata superata da Asciidoctor, un'implementazione Ruby rilasciata nel 2013. Guida pratica: scegli Markdown per post di blog, README, chat, appunti e la maggior parte della documentazione; reStructuredText per la documentazione Python elaborata da Sphinx; AsciiDoc per libri o specifiche long-form che hanno bisogno di rendere a DocBook, PDF ed EPUB simultaneamente con piena fedeltà semantica.

Domande frequenti

Quali funzionalità Markdown sono supportate?

Questo visualizzatore supporta titoli, grassetto, corsivo, link, immagini, elenchi, citazioni, blocchi di codice, tabelle, linee orizzontali e barrato. Copre le specifiche CommonMark più le estensioni comuni.

Posso esportare l'HTML renderizzato?

Puoi copiare l'output renderizzato dal pannello di anteprima. Per l'HTML grezzo, fai clic con il tasto destro sull'anteprima e usa la funzione "Ispeziona" o "Visualizza sorgente" del tuo browser per copiare il markup generato.

Il mio testo viene salvato?

No. Tutto viene eseguito nel tuo browser e nulla viene memorizzato o inviato a un server. Chiudi la scheda e il tuo testo sparisce. Copia il tuo Markdown prima di uscire se vuoi salvarlo.

Il mio testo viene salvato o inviato da qualche parte?

No. Il parser Markdown gira interamente nel tuo browser tramite JavaScript. Niente viene caricato, nessuna API è chiamata, nessun log è scritto. Chiudi la tab e il testo è andato. Se vuoi conservare ciò che hai scritto, copialo prima di lasciare la pagina. Puoi anche usare la pagina offline una volta caricata: il caching tramite service worker significa che il parser resta disponibile senza una connessione internet.

Il previewer sanifica l'HTML grezzo?

Il parser fa passare l'HTML grezzo, che è il comportamento standard CommonMark: utile per incorporare l'occasionale blocco <div> o <details>. Poiché l'input viene dalla tua sessione di browser e l'output è renderizzato solo nella tua tab, questo è sicuro per il caso d'uso preview da una persona per cui è costruito. Se stai pubblicando l'output su un sistema multi-utente (un CMS, un forum, un sito di documentazione che accetta sottomissioni utente) dovresti sempre far passare l'HTML renderizzato attraverso un sanificatore come DOMPurify prima di iniettarlo in una pagina pubblica: Markdown più HTML grezzo è un vettore XSS in qualsiasi sistema in cui lo scrittore e il lettore sono persone diverse.

Ci sono limiti sulla dimensione del file?

Nessun limite rigido. Il parser gestisce decine di migliaia di righe di Markdown senza problemi su un laptop tipico. Il re-render live gira però a ogni battuta di tasto, quindi documenti molto grandi (un libro intero in un singolo file) cominceranno a sembrare lenti su dispositivi più lenti. Dividere in capitoli, o incollare il contenuto per renderizzare una volta e poi modificare offline, è il workaround. La pagina non bloccherà il tuo browser: marked.js è uno dei parser Markdown più veloci disponibili.

Strumenti correlati