CommonMark: Markdown İçin Resmi Bir Spesifikasyon

Yayınlanan: 2022-03-10
Hızlı özet ↬ Markdown, daha sonra ayrıştırılıp HTML olarak işlenebilen düz metin biçiminde düzenlemeye ve biçimlendirmeye izin veren güçlü bir biçimlendirme dilidir. Teknik ve teknik olmayan kişiler için hem güçlü hem de öğrenmesi kolay bildirimsel bir sözdizimine sahiptir. Bununla birlikte, orijinal spesifikasyonundaki sonuç olarak ortaya çıkan belirsizlikler nedeniyle, bu belirsizlikleri ortadan kaldırmanın yanı sıra orijinal sözdizimi desteğini genişletmeyi amaçlayan bir dizi farklı tatlar (veya özel sürümler) olmuştur. Bu, neyin ayrıştırılabileceği ve neyin oluşturulabileceği arasında keskin bir ayrışmaya yol açmıştır. CommonMark, gerçek dünyadaki kullanımını yansıtan standart bir Markdown özelliği sağlamayı amaçlar.

CommonMark, amacı orijinal Markdown spesifikasyonunu çevreleyen belirsizlikleri ve tutarsızlıkları ortadan kaldırmak olan bir spesifikasyona sahip Markdown sözdiziminin rasyonelleştirilmiş bir versiyonudur. Markdown uygulamalarını bu belirtime göre doğrulamak için bir dizi kapsamlı testle birlikte dilin ortak sözdizimini tanımlayan standartlaştırılmış bir belirtim sunar.

GitHub, kullanıcı içeriği için işaretleme dili olarak Markdown'ı kullanır.

“CommonMark, internetteki birçok web sitesi tarafından kullanılan Markdown sözdizimini, gerçek dünyadaki kullanımını yansıtacak şekilde resmi olarak belirtmek için iddialı bir projedir [...] İnsanların, geliştiriciler sunarken Markdown'ı her zaman olduğu gibi kullanmaya devam etmelerini sağlar. Markdown'ı platformlar arasında tutarlı bir şekilde birlikte çalışmak ve görüntülemek için kapsamlı bir spesifikasyon ve referans uygulamaları.”

— "GitHub Aromalı Markdown İçin Resmi Bir Spesifikasyon" GitHub Blogu

2012'de GitHub, Markdown standardizasyonunun eksikliğiyle mücadele etmek ve sözdizimini ihtiyaçlarına göre genişletmek için kendi Markdown lezzetini - GitHub Flavored Markdown (GFM) - yaratmaya başladı. GFM, o sırada mevcut Markdown ayrıştırıcılarının bazı eksikliklerini çözmek için GitHub tarafından özel olarak oluşturulmuş bir ayrıştırıcı olan Sundown'ın üzerine inşa edildi. Beş yıl sonra, 2017'de, CommonMark ayrıştırma ve oluşturma kitaplığı lehine Sundown'ın kullanımdan kaldırıldığını duyurdu, GitHub Flavored Markdown için resmi bir spesifikasyonda cmark.

Markdown ve Visual Studio Code'un Ortak Sorular bölümünde, VSCode'daki Markdown'ın, kendi içinde CommonMark belirtimini izleyen markdown-it kitaplığını kullanarak CommonMark Markdown belirtimini hedeflediği belgelenmiştir.

CommonMark, C (örn. cmark), C# (örn. CommonMark.NET), JavaScript (örn. markdown-it) vb. gibi farklı dillerde kullanım için geniş çapta benimsendi ve uygulandı (bkz. CommonMark Uygulamaları Listesi). Bu, geliştiriciler için iyi bir haber. ve yazarlar, Markdown'ı tutarlı bir sözdizimi ve standartlaştırılmış bir belirtim ile kullanabilme konusunda yavaş yavaş yeni bir sınıra doğru ilerliyorlar.

Markdown Ayrıştırıcıları Üzerine Kısa Bir Not

Markdown ayrıştırıcıları, Markdown metnini doğrudan veya dolaylı olarak HTML'ye dönüştürmenin merkezinde yer alır.

cmark ve commonmark.js gibi ayrıştırıcılar, Markdown'ı doğrudan HTML'ye dönüştürmez, bunun yerine onu bir Soyut Sözdizimi Ağacına (AST) dönüştürür ve ardından AST'yi HTML olarak işleyerek süreci daha ayrıntılı ve manipülasyona açık hale getirir. Ayrıştırma - AST'ye - ve işleme - HTML'ye - örneğin, Markdown metni genişletilebilir.

Atlamadan sonra daha fazlası! Aşağıdan okumaya devam edin ↓

CommonMark'ın Markdown Sözdizimi Desteği

CommonMark belirtimini kendi özel özelliklerinin temel çizgisi olarak zaten uygulayan projeler veya platformlar, genellikle CommonMark Markdown belirtiminin katı alt kümesinin yerine geçer. Çoğunlukla CommonMark, üzerine inşa edilecek bir özellik oluşturarak birçok belirsizliği azalttı. GFM en iyi örnektir, her CommonMark sözdizimini desteklerken, kullanımına uygun şekilde genişletir.

CommonMark'ın sözdizimi desteği ilk başta sınırlı olabilir, örneğin, bu tablo sözdizimi için desteği yoktur, ancak bu konuşma dizisindeki bu yorumun ortaya koyduğu gibi, bunun tasarım gereği olduğunu bilmek önemlidir: desteklenen sözdiziminin katı ve söylendi dilin temel sözdizimi olmak - yaratıcısı John Gruber tarafından Markdown: Syntax'ta belirtilenle aynı.

Yazma sırasında, desteklenen bir dizi sözdizimi şunlardır:

  1. Paragraflar ve Satır Sonları,
  2. başlıklar,
  3. Vurgu ve Güçlü Vurgu,
  4. Yatay Kurallar,
  5. Listeler,
  6. Bağlantılar,
  7. Görüntüler,
  8. blok alıntılar,
  9. kod,
  10. Kod Blokları.

Örnekleri takip etmek için, sözdizimini denemek ve işlenmiş Önizleme, oluşturulan HTML ve AST'yi almak için commonmark.js dingus düzenleyicisini kullanmanız önerilir.

Paragraflar ve Satır Sonları

Markdown'da paragraflar, en az bir boş satırla ayrılmış sürekli metin satırlarıdır.

Aşağıdaki kurallar bir paragrafı tanımlar:

  1. Markdown paragrafları, HTML'de Paragraf öğesi <p> ​​olarak işlenir.
  2. Farklı paragraflar, aralarında bir veya daha fazla boş satırla ayrılır.
  3. Bir satır sonu için, bir paragraf iki boşlukla (veya sekme eşdeğeri) veya ters eğik çizgiyle ( \ ) sonradan sabitlenmelidir.
Sözdizimi İşlenmiş HTML
Bu bir metin satırıdır <p>Bu bir metin satırıdır</p>
Bu bir metin satırıdır
Ve başka bir metin satırı
ve başka ama
aynı paragraf		 <p>Bu bir metin satırıdır
Ve başka bir metin satırı
ve başka ama
aynı paragraf</p>
Bu bir paragraf

Ve başka bir paragraf

Ve başka		 <p>Bu bir paragraftır</p>
<p>Ve bir paragraf daha</p>
<p>Ve bir diğeri</p>
Bir metin satırından sonra iki boşluk
Veya sonradan düzeltilmiş bir ters eğik çizgi\
Her ikisi de satır sonu anlamına gelir		 <p>Bir metin satırından sonra iki boşluk<br /><br>Ya da sonradan düzeltilmiş bir ters eğik çizgi<br /><br>Her ikisi de satır sonu anlamına gelir</p>
  • Paragraflar hakkında bilgi edinmek için etkileşimli öğretici.
  • Dingus kalıcı bağlantısı, Önizleme ve AST ile tam örneğe bakın.
  • Paragraflar hakkında daha fazla bilgi edinin.

Başlıklar

Markdown'daki başlıklar, HTML Başlık öğelerinden birini temsil eder. Başlıkları tanımlamanın iki yolu vardır:

  1. ATX başlığı.
  2. Settext başlığı.

Aşağıdaki kurallar ATX başlıklarını tanımlar:

  1. Başlık seviyesi 1 ( h1 ), başlık seviyesi 6'ya ( h6 ) kadar desteklenir.
  2. Atx stili başlıkların önüne hash ( # ) sembolü eklenir.
  3. Metin ve kare ( # ) sembolü arasında en az bir boşluk bırakılmalıdır.
  4. Karma sayısı, başlığın ana numarasına eşittir. Bir karma h1 , iki karma, h2 , 6 karma, h6 .
  5. Başlıklara rastgele sayıda karma sembol(ler) eklemek de mümkündür, ancak bu herhangi bir etkiye neden olmaz (örneğin # Heading 1 # )
Sözdizimi İşlenmiş HTML
# Başlık 1 <h1>1. Başlık</h1>
## Başlık 2 <h2>Başlık 2</h2>
### Başlık 3 <h3>Başlık 3</h3>
#### Başlık 4 <h4>4. Başlık</h4>
##### Başlık 5 <h5>Başlık 5</h5>
###### Başlık 6 <h6>Başlık 6</h6>
## Başlık 2 ## <h2>Başlık 2</h2>

Aşağıdaki kurallar Settext başlıklarını tanımlar:

  1. Yalnızca Başlık düzeyi 1 (h1) ve başlık düzeyi 2, (h2) desteklenir.
  2. Settext stili tanımlama, sırasıyla eşittir (=) ve tire sembolleriyle yapılır.
  3. Settext ile en az bir eşit veya tire sembolü gereklidir.
Sözdizimi İşlenmiş HTML
Başlık 1
=		 <h1>1. Başlık</h1>
Başlık 2
-		 <h2>Başlık 2</h2>
  • Başlıklar hakkında bilgi edinmek için etkileşimli öğretici.
  • Önizleme ve AST ile tam örneğe göz atmak için kalıcı bağlantı.
  • ATX başlıkları hakkında daha fazla bilgi edinin.
  • Settext başlıkları hakkında daha fazla bilgi edinin.

Vurgu ve Güçlü Vurgu

Markdown'daki vurgu italik veya kalın olabilir (güçlü vurgu).

Aşağıdaki kurallar vurguyu tanımlar:

  1. Sıradan ve güçlü vurgu, HTML'de sırasıyla Vurgu, <em> ve Strong, <strong> öğesi olarak işlenir.
  2. Tek bir yıldız ( * ) veya alt çizgi ( _ ) ile sınırlandırılmış bir metin vurgu olacaktır.
  3. Çift yıldız veya alt çizgi ile sınırlandırılmış bir metin güçlü bir vurgu olacaktır.
  4. Sınırlayıcı semboller (yıldız veya alt çizgi) eşleşmelidir.
  5. Semboller ve ekteki metin arasında boşluk olmamalıdır.
Sözdizimi İşlenmiş HTML
_Italic_ <em>İtalik</em>
*Italic* <em>İtalik</em>
__Bold__ <strong>Kalın</strong>
**Bold** <strong>Kalın</strong>
  • Vurgu hakkında bilgi edinmek için etkileşimli öğretici.
  • Önizleme ve AST ile tam örneğe göz atmak için kalıcı bağlantı.
  • Vurgu ve güçlü vurgu hakkında daha fazla bilgi edinin.

Yatay kural

Bir Yatay kural, <hr/>, yeni bir satırda üç veya daha fazla yıldız işareti ( * ), kısa çizgi ( - ) veya alt çizgi ( _ ) ile oluşturulur. Semboller herhangi bir sayıda boşlukla ayrılır veya hiç ayrılmaz.

Sözdizimi İşlenmiş HTML
*** <saat />
* * * <saat />
--- <saat />
- - - <saat />
___ <saat />
_ _ _ <saat />
  • Önizleme ve AST ile tam örneğe göz atmak için kalıcı bağlantı.
  • Tematik molalar hakkında daha fazla bilgi edinin.

Listeler

Markdown'daki listeler, madde işareti (sırasız) liste veya sıralı listedir.

Aşağıdaki kurallar bir liste tanımlar:

  1. Madde işareti listeleri HTML'de Sırasız liste öğesi <ul> olarak işlenir.
  2. Sıralı listeler HTML'de Sıralı liste öğesi <ol> olarak işlenir.
  3. Madde işaretli listeler, işaretçi olarak yıldız işaretleri, artılar ve kısa çizgiler kullanır.
  4. Sıralı listeler, sayıların ardından nokta veya parantez kapatma kullanır.
  5. İşaretleyiciler tutarlı olmalıdır (liste öğeleri tanımının geri kalanı için yalnızca başladığınız işaretçiyi kullanmalısınız).
Sözdizimi İşlenmiş HTML
* 1
* 2
* üç		 <ul>
<li>bir</li>
<li>iki</li>
<li>üç</li>
</ul>
+ bir
+ iki
+ üç		 <ul>
<li>bir</li>
<li>iki</li>
<li>üç</li>
</ul>
- 1
- 2
- üç		 <ul>
<li>bir</li>
<li>iki</li>
<li>üç</li>
</ul>
- 1
- 2
+ üç		 <ul>
<li>bir</li>
<li>iki</li>
</ul>
<ul>
<li>üç</li>
</ul>
1 bir
2. iki
3. üç		 <ol>
<li>bir</li>
<li>iki</li>
<li>üç</li>
</ol>
3. üç
4. dört
5. beş		 <ol start="3">
<li>üç</li>
<li>dört</li>
<li>beş</li>
</ol>
1 bir
2. iki
3. üç		 <ol>
<li>bir</li>
<li>iki</li>
<li>üç</li>
</ol>
  • Listeler hakkında bilgi edinmek için etkileşimli öğretici.
  • Önizleme ve AST ile tam örneğe göz atmak için kalıcı bağlantı.
  • Liste öğeleri hakkında daha fazla bilgi edinin.

Bağlantılar

Bağlantılar, satır içi ve referans biçimiyle desteklenir.

Aşağıdaki kurallar bir bağlantıyı tanımlar:

  1. Bağlantılar, HTML Bağlantı elemanı <a> olarak işlenir.
  2. Satır içi biçim sözdizimine sahiptir: [value](URL "optional-title") parantezler arasında boşluk yoktur.
  3. Referans biçimi, referans için [value][id] ve köprü etiketi için [id]: href "optional-title" sözdizimine sahiptir ve en az bir satırla ayrılır.
  4. id , Tanım Tanımlayıcıdır ve harfler, sayılar, boşluklar ve noktalama işaretlerinden oluşabilir.
  5. Tanım Tanımlayıcılar büyük/küçük harfe duyarlı değildir.
  6. URL'nin küçüktür (<) ve büyüktür (>) sembolüyle sınırlandığı ve kelimenin tam anlamıyla görüntülendiği Otomatik Bağlantılar için de destek vardır.
 <!--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>
  • Bağlantılar hakkında bilgi edinmek için etkileşimli öğretici.
  • Önizleme ve AST ile tam örneğe göz atmak için kalıcı bağlantı.
  • Bağlantılar hakkında daha fazla bilgi edinin.

Görüntüler

Markdown'daki resimler, Bağlantılar için satır içi ve referans biçimlerini takip eder.

Aşağıdaki kurallar görüntüleri tanımlar:

  1. Görüntüler, HTML görüntü öğesi <img> olarak işlenir.
  2. Satır içi biçim sözdizimine sahiptir: ![alt text](image-url "optional-title") .
  3. Referans formatı, referans için ![alt text][id] ve resim etiketi için [id]: image-url "optional-title" sözdizimine sahiptir. Her ikisi de en az bir boş satırla ayrılmalıdır.
  4. Resim başlığı isteğe bağlıdır ve resim URL'si göreceli olabilir.
 <!--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" />
  • Görüntüler hakkında bilgi edinmek için etkileşimli öğretici.
  • Önizleme ve AST ile tam örneğe göz atmak için kalıcı bağlantı.
  • Görüntüler hakkında daha fazla bilgi edinin.

blok alıntılar

HTML Blok Teklifi öğesi <blockquote>, büyüktür sembolüyle ( > ) yeni bir satırın önüne eklenerek oluşturulabilir.

 <!--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>

Blok alıntılar iç içe yerleştirilebilir:

 <!--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>

Ayrıca başlıklar, kod, liste öğeleri vb. gibi diğer Markdown öğelerini de içerebilirler.

 <!--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>
  • Blok alıntılar hakkında bilgi edinmek için etkileşimli öğretici.
  • Önizleme ve AST ile tam örneğe göz atmak için kalıcı bağlantı.
  • Blok alıntılar hakkında daha fazla bilgi edinin.

kod

HTML Satır İçi Kodu öğesi <code> da desteklenir. Bir tane oluşturmak için metni ters tiklerle (`) veya ek metinde değişmez bir geri tik olması gerekiyorsa çift tik işaretiyle sınırlayın.

 <!--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>
  • Kod hakkında bilgi edinmek için etkileşimli öğretici.
  • Önizleme ve AST ile tam örneğe göz atmak için kalıcı bağlantı.
  • Kod aralıkları hakkında daha fazla bilgi edinin.

Kod Blokları

HTML Önceden Biçimlendirilmiş Metin öğesi <pre> de desteklenir. Bu, en az üç ve eşit sayıda sınırlayıcı geri tik ( ` ) veya tilde ( ~ ) ile yapılabilir - normalde kod çiti olarak adlandırılır veya en az 4 boşluktan başlayan yeni bir satır girintisi.

 <!--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>
  • Kod hakkında bilgi edinmek için etkileşimli öğretici.
  • Önizleme ve AST ile tam örneğe göz atmak için kalıcı bağlantı.
  • Çitle Çevrelenmiş ve Girintili kod blokları hakkında daha fazla bilgi edinin.

Satır İçi HTML'yi Kullanma

John Grubers'ın satır içi HTML hakkındaki orijinal spesifikasyon notuna göre , Markdown'ın sözdizimi tarafından kapsanmayan herhangi bir işaretleme, yalnızca HTML'nin kendisini kullanırsınız, tek kısıtlama blok düzeyindeki HTML öğeleridir - örneğin <div> , <table> , <pre> , <p> , vb. — çevreleyen içerikten boş satırlarla ayrılmalı ve bloğun başlangıç ​​ve bitiş etiketleri sekmeler veya boşluklarla girintili olmamalıdır.

Bununla birlikte, muhtemelen CommonMark'ın arkasındaki kişilerden biri değilseniz veya o civarda, büyük olasılıkla Markdown'ı şu anda CommonMark tarafından desteklenmeyen çok sayıda sözdizimini işlemek için zaten genişletilmiş bir çeşniyle yazacaksınız.

İleriye gidiyor

CommonMark, en son 6 Nisan 2019'da güncellenen spesifikasyonu ile sürekli olarak devam eden bir çalışmadır. Markdown araçları havuzunda onu destekleyen bir dizi popüler uygulama vardır. CommonMark'ın standardizasyona yönelik çabasının bilinciyle, Markdown'ın basitliğinde, sahne arkasında çok fazla iş yapıldığı ve GitHub Flavored Markdown'ın resmi spesifikasyonunun CommonMark çabası için iyi bir şey olduğu sonucuna varmanın yeterli olduğunu düşünüyorum. şartnameye dayanmaktadır.

CommonMark standardizasyon çabasına doğru hareket, desteklenen sözdizimini genişletmek için tatların oluşturulmasını engellemez ve CommonMark çözülmesi gereken sorunlarla 1.0 sürümüne hazırlanırken, sürekli çaba hakkında kullanabileceğiniz bazı ilginç kaynaklar var. inceleme.

Kaynaklar

  • John Gruber tarafından Markdown ile tanışın
  • CommonMark resmi web sitesi
  • GitHub Aromalı Markdown Spesifikasyonu
  • cmark resmi repo
  • GitHub'ın cmark çatalı
  • Wikipedia'da işaretleme
  • İşaretleme Kılavuzu