Markdown näme? Sintaksis, CommonMark we GFM

Programma taslamasynyň README faýlyny, bellik programmasyndaky sözbaşyly sanawlary ýa-da söhbetdeşlik programmasynda ýyldyzjyklar bilen galyň edýän sözleriňizi göz öňüne getiriň. Olaryň hemmesiniň aňyrsynda şol bir pikir bar: Markdown. Markdown ýönekeý tekste birnäçe ýönekeý nyşan goşup, sözbaşylary, sanawlary, salgylary we tablisalary kesgitlemäge mümkinçilik berýän ýeňil bellik dilidir. Faýl islendik tekst redaktorynda okalýan bolup galýar, ýöne gerek bolan wagty ony arassa HTML sahypasyna, Word resminamasyna ýa-da PDF-e öwrüp bolýar. Bu makalada Markdown-yň nähili döränligi, esasy sintaksisi, CommonMark bilen GitHub Flavored Markdown-yň arasyndaky tapawutlar we MD faýllaryny öwürende nämä üns bermelidigi düşündirilýär.

Markdown näme?

Markdown hem ýazuw düzgünleriniň toplumy, hem-de şol düzgünler bilen ýazylan teksti HTML-e öwürýän gurallaryň umumy adydyr. Faýllar adatça .md ýa-da .markdown giňeltmesi bilen ýatda saklanýar. Onuň döredijisi John Gruber-iň aýtmagyna görä, esasy dizaýn maksady okalyjylykdyr: Markdown resminamasy tegler ýa-da formatlama görkezmeleri bilen bellenen ýaly görünmän, ýönekeý tekst hökmünde şol durşuna çap edilip bilinmeli. HTML-de <strong>möhüm</strong> gerek bolan ýerinde Markdown **möhüm** ulanýar we hatda çig görnüşi hem tebigy okalýar.

Gysgaça taryhy

John Gruber Markdown-y 2004-nji ýylda döretdi, Aaron Swartz bolsa onuň pikirlerini ara alyp maslahatlaşýan hyzmatdaş hökmünde goşant goşdy. Sintaksis ýönekeý tekstli e-poçtanyň düzgünlerine (nygtamak üçin ýyldyzjyklar, sanawlar üçin defisler) we setext hem Textile ýaly öňki bellik dillerine daýandy. Gruber-iň Daring Fireball saýtynda çap eden Perl skripti Markdown.pl-iň 1.0.1 wersiýasy 2004-nji ýylyň 17-nji dekabryna degişli.

Emma Gruber-iň beýany resmi spesifikasiýa däl-de, mysallar arkaly düşündirişdi. Düşnüksiz ýagdaýlar (içki sanawlar, içe süýşürilen kod bloklary, HTML-i garyşdyrmak) her durmuşa geçirişi öz saýlawyny etmäge mejbur etdi we şol bir tekst dürli gurallarda dürli netije berip başlady. Muňa iki esasy jogap boldy:

• CommonMark (2014): John MacFarlane-iň ýolbaşçylygyndaky, Markdown-y birmanyly kesgitleýän we ony ýüzlerçe mysal bilen barlap bolýan edýän spesifikasiýa. Ilkinji wersiýalary 2014-nji ýylyň güýzünde çykdy; häzirki wersiýasy 2024-nji ýylyň 28-nji ýanwaryna degişli 0.31.2. Spesifikasiýa entek 1.0 diýlip yglan edilmedi.
• GitHub Flavored Markdown (GFM, 2017): GitHub-yň CommonMark-yň üstünde guran resmi spesifikasiýasy. Ol tablisalar, ýumuş sanawlary, üsti çyzylan tekst, giňeldilen awtosalgylar we howpsuzlyk üçin käbir çig HTML teglerini süzmek ýaly giňeltmeleri goşýar. Iň soňky çap edilen spesifikasiýasy 2019-njy ýylyň 6-njy aprelindäki 0.29-gfm.

Markdown internet infrastrukturasynda hem ykrar edildi: 2016-njy ýylyň martynda çap edilen RFC 7763 text/markdown media görnüşini (MIME görnüşini) awtoryň haýsy Markdown görnüşini göz öňünde tutandygyny görkezýän islege bagly variant parametri bilen hasaba aldy.

Markdown-yň esasy görnüşleri

CommonMark we GFM-den başga-da giň ýaýran görnüşler bar. RFC 7763 bilen bilelikde çap edilen RFC 7764 olaryň birnäçesini hasaba aldy we ulanmak boýunça maslahat berdi:

• Markdown Extra: bellikleri, kesgitleme sanawlaryny we tablisalary goşan irki giňeltme.
• MultiMarkdown: metamaglumatlar, sitatalar we içerki salgylanmalar bilen ylmy ýazuwa gönükdirilen görnüş.
• Pandoc Markdown: Pandoc öwrüjisiniň ulanýan görnüşi, kitap we makala ýazmak üçin köp giňeltmesi bar.

Amaly düzgün: resminamaňyz diňe sözbaşylary, sanawlary, salgylary, kody we ýönekeý tablisalary ulanýan bolsa, ol diýen ýaly hemme ýerde birmeňzeş görner. Bellikler, kesgitleme sanawlary ýa-da ýörite blok görnüşleri gerek bolsa, maksat gurşawyň haýsy görnüşi goldaýandygyny barlaň.

Esasy sintaksis

Markdown-yň gündelik gerek bolan bölegini öwrenmek birnäçe minut alýar:

# Birinji derejeli sözbaşy
## Ikinji derejeli sözbaşy
Bu abzasda **galyň**, *kursiw* we `kod` bar.
- Nokatly sanaw
- Ikinji element
  - Içe süýşürilen kiçi element
1. Belgili sanaw
2. Ikinji ädim
[Salgy teksti](https://example.com)
![Suratyň beýany](surat.png)
> Sitata bloky
```
Köp setirli kod bloky
```

GFM-iň goşan tablisalary we ýumuş sanawlary şeýle görünýär:

| Format | Giňeltme |
|--------|----------|
| Markdown | .md |
| Ýönekeý tekst | .txt |
- [x] Garalamany ýaz
- [ ] Gözden geçir

Abzaslar boş setirler bilen bölünýär. Ýeke setir geçişi köp durmuşa geçirişlerde şol abzasyň bir bölegi hasaplanýar; setiri mejbury geçirmek üçin setiri iki boşluk bilen tamamlaň. Markdown-yň içinde göni HTML hem ýazyp bolýar. CommonMark muňa rugsat berýär, ýöne GFM ýaly gurşawlar howpsuzlyk üçin käbir tegleri petikleýär.

Markdown nirede ulanylýar?

• Programma işläp düzmek: README-ler, üýtgeşmeler sanawy we goşant gollanmalary, şeýle hem GitHub we GitLab ýaly platformalardaky meseleler we kod synyndaky teswirler.
• Tehniki resminamalaşdyrma: Markdown faýllaryndan web saýtlary gurýan statik saýt generatorlary.
• Bellik ýazmak: köp bellik programmalary bellikleri Markdown görnüşinde saklaýar ýa-da eksport edýär.
• Söhbetdeşlik we jemgyýet platformalary: Reddit we Discord ýaly platformalar Markdown görnüşlerini ulanýar.
• Ýazuw we neşir: Pandoc ýaly gurallar bilen ýeke Markdown çeşmesinden HTML, PDF, DOCX we EPUB döretmek.
• Emeli aň gurallary: söhbetdeşlik esasly emeli aň kömekçileri jogaplaryny köplenç Markdown-da formatlaýar.

Güýçli we gowşak taraplary

Markdown-y haýsy programmalar açýar?

Markdown ýönekeý tekst bolany üçin islendik tekst redaktorynda, şol sanda Notepad-da we TextEdit-de açylýar. Formatlanan deslapky görnüş üçin Visual Studio Code-yň içine gurlan Markdown deslapky görnüşini ýa-da Obsidian we Typora ýaly ýörite redaktorlary ulanyp bilersiňiz. GitHub we GitLab ammarlardaky .md faýllaryny awtomatik görkezýär. Word bolsa Markdown-y formatlanan tekst hökmünde açmaýar, şonuň üçin faýly ilki öwürmeli.

Ýygy duş gelýän meseleler we olary çözmek

Sanaw ýa-da sözbaşy görkezilmeýär

CommonMark sözbaşy belgisinden soň boşluk talap edýär: ##Sözbaşy däl-de, ## Sözbaşy. Abzasdan soň gelýän sanaw hem dogry görkezilmegi üçin köplenç arada boş setir talap edýär.

Setirler birleşýär

Ýeke setir geçişi abzasy bölmeýär. Täze abzas üçin boş setir galdyryň ýa-da abzasyň içinde setiri geçirmek üçin setiri iki boşluk bilen tamamlaň.

Tablisa bir platformada işleýär, beýlekisinde işlemeýär

Tablisalar Gruber-iň asyl Markdown-yna ýa-da CommonMark-yň özenine girmeýär; olar GFM ýaly giňeltmelerden gelýär. Maksat platformanyň haýsy görnüşi goldaýandygyny barlaň.

San bilen başlaýan abzas belgili sanawa öwrülýär

"2024. Ýyl gaty işli geçdi" ýaly setir sanlar we nokat bilen başlaýar, şonuň üçin sanaw hökmünde derňelip bilner. Munuň öňüni almak üçin nokady ters ýapgyt çyzyk bilen goraň (2024\.).

Markdown faýllaryny öwürmek boýunça maslahatlar

Biziň öwrüjimizde Markdown faýllary serwerimize ýüklenýär we 30 minut içinde pozulýar. Okamak üçin CommonMark we GitHub görnüşli giňeltmeler (tablisalar, ýumuş sanawlary, bellikler, awtosalgylar) bilen Markdig kitaphanasyny ulanýarys.

• Markdown-dan PDF-e we Markdown-dan Word-a öwürmek sözbaşylary, sanawlary, kod bloklaryny, sitata bloklaryny we serhetli tablisalary saklaýar. Ýumuş sanawynyň belgi gutulary Word-da we PDF-de görünýän bolup galsyn diýip ☑ we ☐ nyşanlaryna öwrülýär. Tekst adaty ýagdaýda 12 pt serif şriftde, kod bloklary bolsa deň giňlikli şriftde ýazylýar.
• Markdown-dan HTML-e öwürmek README-ni nyşan kodlamasy yglan edilen özbaşdak web sahypasyna öwürýär.
• Ters ugurda Word-dan Markdown-a, HTML-den Markdown-a we PDF-den Markdown-a öwürmek GitHub bilen gabat gelýän Markdown döredýär: sözbaşylar, galyň we kursiw tekst, sanawlar, tablisalar, salgylar, kod bloklary we sitata bloklary saklanýar; şriftler, reňkler we sahypa maketi aýrylýar. Sözbaşy setiri bolmadyk tablisalarda birinji setir sözbaşy bolýar, sebäbi GFM tablisalary ony talap edýär. "1. Bent" ýaly san bilen başlaýan ýönekeý abzaslar tötänleýin sanawa öwrülmez ýaly goralýar. Faýl BOM-syz UTF-8 hökmünde ýatda saklanýar.

Köp berilýän soraglar

MD faýlyny nädip açmaly?

Islendik tekst redaktory ony açar. Formatlanan görnüşde görmek üçin Visual Studio Code-yň deslapky görnüşini ýa-da Markdown redaktoryny ulanyň; ony Word-da okamak isleseňiz, DOCX-e öwüriň.

CommonMark bilen GitHub Flavored Markdown-yň arasynda nähili tapawut bar?

CommonMark Markdown-yň esasy sintaksisini takyk düzgünler bilen kesgitleýär. GFM bolsa CommonMark-yň üstüne tablisalar, ýumuş sanawlary, üsti çyzylan tekst we giňeldilen awtosalgylar ýaly giňeltmeleri goşýan giňeldilen toplumdyr.

Markdown-da tablisa döredip bolarmy?

Hawa, GFM ýaly giňeltmeler bilen dik çyzyklary we defisleri ulanyp ýönekeý tablisalar ýazyp bilersiňiz. Birleşdirilen öýjükler ýaly çylşyrymly gurluşlar üçin HTML tablisasyny ulanyň ýa-da resminamany Word-da taýýarlaň.

Markdown bilen HTML-iň arasynda nähili tapawut bar?

Markdown HTML-e öwrülmek üçin niýetlenen has ýönekeý ýazuw formatydyr. Ol HTML-iň aňladyp bilýän zatlarynyň hemmesini aňladyp bilmeýär, ýöne çig görnüşi has okalýar. Gerek bolanda Markdown-yň içinde HTML hem ýazyp bilersiňiz.

Markdown-yň resmi standarty barmy?

Gruber-iň asyl beýany resmi spesifikasiýa däl. Häzir iň giňden kabul edilen takyk kesgitleme CommonMark-dyr, text/markdown media görnüşi bolsa 2016-njy ýylyň martynda RFC 7763 bilen hasaba alyndy.

Çeşmeler

• John Gruber, Daring Fireball: Markdown
• CommonMark Spec (wersiýalaryň taryhy)
• GitHub Flavored Markdown Spec
• IETF RFC 7763: The text/markdown Media Type (2016-njy ýylyň marty)
• IETF RFC 7764: Guidance on Markdown
• Wikipedia: Markdown (taryhy, ikinji derejeli çeşme)
• Markdig: .NET üçin CommonMark bilen gabat gelýän Markdown işleýji