CommonMark: O specificație formală pentru Markdown

CommonMark este o versiune raționalizată a sintaxei Markdown cu o specificație al cărei scop este să elimine ambiguitățile și inconsecvența din jurul specificației originale Markdown. Oferă o specificație standardizată care definește sintaxa comună a limbajului împreună cu o suită de teste cuprinzătoare pentru a valida implementările Markdown în raport cu această specificație.

GitHub folosește Markdown ca limbaj de marcare pentru conținutul utilizatorului.

„CommonMark este un proiect ambițios de a specifica în mod oficial sintaxa Markdown utilizată de multe site-uri web de pe internet într-un mod care să reflecte utilizarea sa în lumea reală [...] Le permite oamenilor să continue să folosească Markdown în același mod în care au făcut-o întotdeauna, oferind dezvoltatorilor o specificație cuprinzătoare și implementări de referință pentru a interopera și afișa Markdown într-un mod consistent între platforme.”

— „O specificație formală pentru Markdown cu aromă GitHub”, Blogul GitHub

În 2012, GitHub a început să creeze propria sa aromă de Markdown — GitHub Flavoured Markdown (GFM) — pentru a combate lipsa standardizării Markdown și a extinde sintaxa la nevoile sale. GFM a fost construit pe Sundown, un parser construit special de GitHub pentru a rezolva unele dintre deficiențele analizatoarelor Markdown existente la acea vreme. La cinci ani după, în 2017, a anunțat renunțarea la Sundown în favoarea bibliotecii de analiză și randare CommonMark, marcat în O specificație formală pentru GitHub Flavored Markdown.

În secțiunea Întrebări comune din Markdown și Visual Studio Code, este documentat că Markdown în VSCode vizează specificația CommonMark Markdown folosind biblioteca markdown-it, care în sine urmează specificația CommonMark.

CommonMark a fost adoptat și implementat pe scară largă (vezi Lista implementărilor CommonMark) pentru utilizare în diferite limbi precum C (de exemplu, cmark), C# (de exemplu, CommonMark.NET), JavaScript (de exemplu, markdown-it) etc. Aceasta este o veste bună ca dezvoltatori iar autorii trec treptat la o nouă frontieră de a putea folosi Markdown cu o sintaxă consecventă și o specificație standardizată.

O scurtă notă despre analizatoarele Markdown

Analizatorii Markdown sunt în centrul conversiei textului Markdown în HTML, direct sau indirect.

Analizoarele precum cmark și commonmark.js nu convertesc Markdown direct în HTML, în schimb, îl convertesc într-un arbore de sintaxă abstractă (AST) și apoi redă AST ca HTML, făcând procesul mai granular și supus manipulării. Între analizarea — la AST — și redarea — la HTML — de exemplu, textul Markdown ar putea fi extins.

Suport pentru sintaxă Markdown de la CommonMark

Proiectele sau platformele care implementează deja specificația CommonMark ca linie de bază a aromei lor specifice sunt adesea supraseturile subsetului strict al specificației CommonMark Markdown. În cea mai mare parte, CommonMark a atenuat o mulțime de ambiguități prin construirea unei specificații care este construită pentru a fi construită. GFM este un exemplu excelent, deși acceptă fiecare sintaxă CommonMark, o extinde și pentru a se potrivi utilizării sale.

Suportul pentru sintaxa CommonMark poate fi limitat la început, de exemplu, nu are suport pentru această sintaxă de tabel, dar este important să știți că acest lucru este prin proiect, așa cum dezvăluie acest comentariu din acest fir de conversație: că sintaxa acceptată este strictă și a spus să fie sintaxa de bază a limbajului în sine - aceeași specificată de creatorul său, John Gruber în Markdown: Syntax.

La momentul scrierii, iată o serie de sintaxe acceptate:

1. Paragrafe și întreruperi de rând,
2. Anteturi,
3. Accent și accent puternic,
4. Reguli orizontale,
5. Liste,
6. Linkuri,
7. Imagini,
8. Citate bloc,
9. Cod,
10. Blocuri de cod.

Pentru a urma exemplele, se recomandă să utilizați editorul dingus commonmark.js pentru a încerca sintaxa și pentru a obține previzualizarea redată, HTML generat și AST.

Paragrafe și întreruperi de rând

În Markdown, paragrafele sunt linii continue de text separate de cel puțin o linie goală.

Următoarele reguli definesc un paragraf:

1. Paragrafele markdown sunt redate în HTML ca element Paragraph, <p>.
2. Diferitele paragrafe sunt separate cu una sau mai multe linii goale între ele.
3. Pentru o întrerupere de linie, un paragraf ar trebui să fie post-fixat cu două spații goale (sau echivalentul său de tablă) sau o bară oblică inversă ( \ ).

• Tutorial interactiv pentru a afla mai multe despre paragrafe.
• Permalink Dingus, consultați exemplul complet cu Preview și AST.
• Aflați mai multe despre paragrafe.

Titluri

Titlurile din Markdown reprezintă unul dintre elementele de titlu HTML. Există două moduri de a defini titlurile:

1. Poziție ATX.
2. Setext titlu.

Următoarele reguli definesc titlurile ATX:

1. Nivelul de titlu 1 ( h1 ), până la nivelul de titlu 6, ( h6 ) sunt acceptate.
2. Titlurile în stil Atx sunt prefixate cu simbolul hash ( # ).
3. Trebuie să existe cel puțin un spațiu liber care să separe textul și simbolul hash ( # ).
4. Numărul hashurilor este echivalent cu numărul cardinal al titlului. Un hash este h1 , două hash, h2 , 6 hash, h6 .
5. De asemenea, este posibil să adăugați un număr arbitrar de simbol(e) hash la titluri, deși acest lucru nu produce niciun efect (adică # Heading 1 # )

Următoarele reguli definesc titlurile Setext:

1. Sunt acceptate doar nivelul de titlu 1 (h1) și nivelul de titlu 2 (h2).
2. Definiția în stilul setext se face cu simbolurile egal (=) și, respectiv, liniuță.
3. Cu Setext, este necesar cel puțin un simbol egal sau liniuță.

• Tutorial interactiv pentru a afla despre titluri.
• Permalink Dingus pentru a vedea exemplul complet cu Preview și AST.
• Aflați mai multe despre titlurile ATX.
• Aflați mai multe despre titlurile Setext.

Accent și accent puternic

Accentul în Markdown poate fi fie cursiv, fie aldine (accent puternic).

Următoarele reguli definesc accentul:

1. Accentul obișnuit și puternic sunt redate în HTML ca elementul Emphasis, <em> și, respectiv, Strong, <strong>.
2. Un text delimitat de un singur asterisc ( * ) sau subliniere ( _ ) va fi un accent.
3. Un text delimitat de asteriscuri duble sau de subliniere va fi un accent puternic.
4. Simbolurile de delimitare (asteriscuri sau liniuță de subliniere) trebuie să se potrivească.
5. Nu trebuie să existe spațiu între simboluri și textul anexat.

• Tutorial interactiv pentru a afla despre accent.
• Permalink Dingus pentru a vedea exemplul complet cu Preview și AST.
• Aflați mai multe despre accent și accent puternic.

Regula orizontală

O regulă orizontală, <hr/> este creată cu trei sau mai multe asteriscuri ( * ), cratime ( - ) sau liniuțe de subliniere ( _ ), pe o nouă linie. Simbolurile sunt separate prin orice număr de spații, sau deloc.

• Permalink Dingus pentru a vedea exemplul complet cu Preview și AST.
• Aflați mai multe despre pauze tematice.

Liste

Listele din Markdown sunt fie o listă cu marcatori (neordonată), fie o listă ordonată.

Următoarele reguli definesc o listă:

1. Listele cu marcatori sunt redate în HTML ca element de listă neordonată, <ul>.
2. Listele ordonate sunt redate în HTML ca element Listă ordonată, <ol>.
3. Listele cu marcatori folosesc asteriscuri, plusuri și cratime ca marcatori.
4. Listele ordonate folosesc numere urmate de puncte sau paranteze de închidere.
5. Markerii trebuie să fie consecvenți (trebuie să utilizați doar marcatorul cu care începeți pentru restul definiției elementelor din listă).

• Tutorial interactiv pentru a afla despre liste.
• Permalink Dingus pentru a vedea exemplul complet cu Preview și AST.
• Aflați mai multe despre articolele din Listă.

Legături

Linkurile sunt acceptate cu formatul inline și de referință .

Următoarele reguli definesc o legătură:

1. Linkurile sunt redate ca element HTML Anchor, <a>.
2. Formatul inline are sintaxa: [value](URL "optional-title") fără spațiu între paranteze.
3. Formatul de referință are sintaxa: [value][id] pentru referință și [id]: href "optional-title" pentru eticheta hyperlink, separate cu cel puțin o linie.
4. id -ul este identificatorul definiției și poate consta din litere, cifre, spații și semne de punctuație.
5. Identificatorii de definiție nu fac distincție între majuscule și minuscule.
6. Există, de asemenea, suport pentru legăturile automate, unde URL-ul este delimitat de simbolul mai mic decât (<) și mai mare decât (>) și este afișat literal.

 <!--Markdown--> [Google](https://google.com “Google”) <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> [Google](https://google.com) <!--Rendered HTML--> <a href="https://google.com">Google</a> <!--Markdown--> [Comparing Styling Methods in Next.js](/2020/09/comparing-styling-methods-next-js) <!--Rendered HTML--> <a href="/2020/09/comparing-styling-methods-next-js">Comparing Styling Methods In Next.js</a> <!--Markdown--> [Google][id] <!--At least a line must be in-between--> <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> <https://google.com> <!--Rendered HTML--> <a href="https://google.com">google.com</a> <!--Markdown--> <[email protected]> <!--Rendered HTML--> <a href="mailto:[email protected]">[email protected]</a>

• Tutorial interactiv pentru a afla despre linkuri.
• Permalink Dingus pentru a vedea exemplul complet cu Preview și AST.
• Aflați mai multe despre Linkuri.

Imagini

Imaginile din Markdown urmează formatele inline și de referință pentru Link-uri.

Următoarele reguli definesc imaginile:

1. Imaginile sunt redate ca element de imagine HTML, <img>.
2. Formatul inline are sintaxa: ![alt text](image-url "optional-title") .
3. Formatul de referință are sintaxa: ![alt text][id] pentru referință și [id]: image-url "optional-title" pentru eticheta imaginii. Ambele trebuie separate de cel puțin o linie goală.
4. Titlul imaginii este opțional, iar URL-ul imaginii poate fi relativ.

 <!--Markdown--> ![alt text](image-url "optional-title") <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" /> <!--Markdown--> ![alt text][id] <!--At least a line must be in-between--> <!--Markdown--> <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" />

• Tutorial interactiv pentru a afla despre imagini.
• Permalink Dingus pentru a vedea exemplul complet cu Preview și AST.
• Aflați mai multe despre Imagini.

Citate bloc

Elementul HTML Block Quotation, <blockquote>, poate fi creat prin prefixarea unei linii noi cu simbolul mai mare decât ( > ).

 <!--Markdown--> > This is a blockquote element > You can start every new line > with the greater than symbol. > That gives you greater control > over what will be rendered. <!--Rendered HTML--> <blockquote> <p>This is a blockquote element You can start every new line with the greater than symbol. That gives you greater control over what will be rendered.</p> </blockquote>

Citatele bloc pot fi imbricate:

 <!--Markdown--> > Blockquote with a paragraph >> And another paragraph >>> And another <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <blockquote> <p>And another paragraph</p> <blockquote> <p>And another</p> </blockquote> </blockquote> </blockquote>

Ele pot conține, de asemenea, alte elemente Markdown, cum ar fi antete, cod, elemente din listă și așa mai departe.

 <!--Markdown--> > Blockquote with a paragraph > # Heading 1 > Heading 2 > - > 1. One > 2. Two <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <h1>Heading 1</h1> <h2>Heading 2</h2> <ol> <li>One</li> <li>Two</li> </ol> </blockquote>

• Tutorial interactiv pentru a afla despre citatele bloc.
• Permalink Dingus pentru a vedea exemplul complet cu Preview și AST.
• Aflați mai multe despre Blockquotes.

Cod

Elementul HTML Inline Code, <code>, este de asemenea acceptat. Pentru a crea unul, delimitați textul cu bifări înapoi (`) sau cu bifări înapoi duble dacă trebuie să existe o bifare înapoi literală în textul alăturat.

 <!--Markdown--> `inline code snippet` <!--Rendered HTML--> <code>inline code snippet</code> <!--Markdown--> `<button type='button'>Click Me</button>` <!--Rendered HTML--> <code><button type='button'>Click Me</button></code> <!--Markdown--> `` There's an inline back-tick (`). `` <!--Rendered HTML--> <code>There's an inline back-tick (`).</code>

• Tutorial interactiv pentru a afla despre cod.
• Permalink Dingus pentru a vedea exemplul complet cu Preview și AST.
• Aflați mai multe despre intervalele de cod.

Blocuri de cod

Elementul de text preformatat HTML, <pre>, este de asemenea acceptat. Acest lucru se poate face cu cel puțin trei și un număr egal de delimitări înapoi ( ` ) sau tilde ( ~ ) - denumite în mod normal un gard de cod sau o nouă linie care începe indentarea de cel puțin 4 spații.

 <!--Markdown--> ``` const dedupe = (array) => [...new Set(array)]; ``` <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre> <!--Markdown--> const dedupe = (array) => [...new Set(array)]; <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre>

• Tutorial interactiv pentru a afla despre cod.
• Permalink Dingus pentru a vedea exemplul complet cu Preview și AST.
• Aflați mai multe despre blocurile de cod îngrădite și indentate.

Folosind HTML inline

Conform specificațiilor originale ale lui John Grubers despre HTML inline, orice marcaj care nu este acoperit de sintaxa lui Markdown, pur și simplu utilizați HTML în sine, cu Singurele restricții sunt că elementele HTML la nivel de bloc - de exemplu <div> , <table> , <pre> , <p> , etc. — trebuie să fie separate de conținutul înconjurător prin linii goale, iar etichetele de început și de sfârșit ale blocului nu trebuie să fie indentate cu file sau spații.

Cu toate acestea, cu excepția cazului în care sunteți probabil unul dintre cei din spatele CommonMark în sine, sau cam așa, cel mai probabil veți scrie Markdown cu o aromă care este deja extinsă pentru a gestiona un număr mare de sintaxe care nu sunt suportate în prezent de CommonMark.

Mergand inainte

CommonMark este o activitate constantă, cu specificațiile actualizate ultima dată pe 6 aprilie 2019. Există o serie de aplicații populare care îl susțin în grupul de instrumente Markdown. Având în vedere efortul de standardizare al CommonMark, cred că este suficient să concluzionăm că, în simplitatea lui Markdown, se lucrează mult în culise și că este un lucru bun pentru efortul CommonMark ca specificația oficială a GitHub Flavored Markdown se bazează pe specificație.

Trecerea către efortul de standardizare CommonMark nu împiedică crearea de arome pentru a-și extinde sintaxa acceptată și, pe măsură ce CommonMark se pregătește pentru versiunea 1.0 cu probleme care trebuie rezolvate, există câteva resurse interesante despre efortul continuu pe care îl puteți folosi pentru dvs. examinare atentă.

Resurse

• Vă prezentăm Markdown de John Gruber
• Site-ul oficial CommonMark
• Spec. Markdown cu aromă GitHub
• cmark repo oficial
• Bifurcația de cmark a GitHub
• Markdown pe Wikipedia
• Ghid de reducere