Markdown деген эмне? Синтаксис, CommonMark жана GFM

Программалык долбоордун README файлын, эскертме тиркемесиндеги аталыштуу тизмелерди же чат тиркемесинде жылдызчалар менен калың кылган сөздөрүңүздү элестетиңиз. Алардын баарынын артында бир эле идея турат: Markdown. Markdown жөнөкөй текстке бир нече жөнөкөй белги кошуу менен аталыштарды, тизмелерди, шилтемелерди жана таблицаларды аныктоого мүмкүндүк берген жеңил белгилөө тили. Файл каалаган текст редакторунда окула берет, бирок керек болгондо аны таза HTML барагына, Word документине же PDF'ке айландырса болот. Бул макалада Markdown кантип пайда болгону, анын негизги синтаксиси, CommonMark менен GitHub Flavored Markdown'дун айырмалары жана MD файлдарын конвертациялоодо эмнеге көңүл буруу керектиги каралат.

Markdown деген эмне?

Markdown бир эле учурда жазуу эрежелеринин жыйындысы жана ошол эрежелер менен жазылган текстти HTML'ге айландырган куралдардын жалпы аты. Файлдар адатта .md же .markdown кеңейтүүсү менен сакталат. Анын жаратуучусу Джон Грубердин айтымында, долбоорлоонун башкы максаты окулуучулук: Markdown документин тегдер же форматтоо буйруктары менен белгиленгендей көрүнбөй, жөнөкөй текст катары ошол бойдон жарыялоого болушу керек. HTML'де <strong>маанилүү</strong> керек болгон жерде Markdown **маанилүү** колдонот, жана чийки нускасы да табигый окулат.

Кыскача тарых

Джон Грубер Markdown'ду 2004-жылы түзгөн, ал эми Аарон Шварц анын идеяларын талкуулоочу катары салым кошкон. Синтаксис жөнөкөй тексттик email'дин эрежелерине (басым үчүн жылдызчалар, тизмелер үчүн дефистер) жана setext, Textile сыяктуу мурунку белгилөө тилдерине таянган. Грубер өзүнүн Daring Fireball сайтында жарыялаган Markdown.pl Perl скриптинин 1.0.1 версиясы 2004-жылдын 17-декабрына таандык.

Бирок Грубердин сүрөттөмөсү расмий спецификация эмес, мисалдар аркылуу түшүндүрүү болгон. Бир маанилүү эмес учурлар (уяланган тизмелер, чегинүү менен жазылган код блоктору, HTML аралаштыруу) ар бир ишке ашырууну өз алдынча чечим кабыл алууга мажбурлап, бир эле текст ар түрдүү куралдарда ар башка натыйжа бере баштаган. Буга эки негизги жооп болгон:

• CommonMark (2014): Джон Макфарлейн жетектеген, Markdown'ду бир маанилүү аныктап, жүздөгөн мисалдар менен текшерилүүчү кылган спецификация. Алгачкы версиялар 2014-жылдын күзүндө чыккан; учурдагы версиясы 2024-жылдын 28-январына таандык 0.31.2. Спецификация азырынча 1.0 деп жарыялана элек.
• GitHub Flavored Markdown (GFM, 2017): GitHub'тун CommonMark'тын үстүнө курулган расмий спецификациясы. Ал таблицалар, тапшырмалар тизмелери, сызылган текст, кеңейтилген автошилтемелер сыяктуу кеңейтүүлөрдү жана коопсуздук үчүн айрым чийки HTML тегдерин чыпкалоону кошот. Акыркы жарыяланган спецификациясы 2019-жылдын 6-апрелине таандык 0.29-gfm.

Markdown интернет инфраструктурасында да таанылган: 2016-жылдын мартында жарыяланган RFC 7763 text/markdown медиа түрүн (MIME түрү) катталган, ал автор кайсы Markdown түрүн көздөгөнүн көрсөткөн милдеттүү эмес variant параметрине ээ.

Markdown'дун негизги түрлөрү

CommonMark жана GFM'ден тышкары башка кеңири таралган түрлөрү да бар. RFC 7763 менен катар жарыяланган RFC 7764 алардын бир нечесин каттап, колдонуу боюнча сунуштарды берген:

• Markdown Extra: шилтемелерди (сноскаларды), аныктамалар тизмелерин жана таблицаларды кошкон алгачкы кеңейтүү.
• MultiMarkdown: метаберилиштер, цитаталар жана кайчылаш шилтемелер менен академиялык жазууга багытталган түр.
• Pandoc Markdown: Pandoc конвертери колдонгон, китептерди жана макалаларды жазуу үчүн көп кеңейтүүлөрү бар түр.

Практикалык эреже: документиңизде аталыштар, тизмелер, шилтемелер, код жана жөнөкөй таблицалар гана болсо, ал дээрлик бардык жерде бирдей көрүнөт. Сноскаларга, аныктамалар тизмелерине же атайын блок түрлөрүнө таянсаңыз, максаттуу чөйрө кайсы түрдү колдой турганын текшериңиз.

Негизги синтаксис

Markdown'дун күнүмдүк колдонууга керектүү бөлүгүн бир нече мүнөттө үйрөнсө болот:

# Биринчи деңгээлдеги аталыш
## Экинчи деңгээлдеги аталыш
Бул абзацта **калың**, *курсив* жана `код` бар.
- Белгиленген тизме
- Экинчи пункт
  - Чегинилген ички пункт
1. Номерленген тизме
2. Экинчи кадам
[Шилтеменин тексти](https://example.com)
![Сүрөттүн сүрөттөмөсү](image.png)
> Цитата
```
Көп саптуу код блогу
```

GFM кошкон таблицалар жана тапшырмалар тизмелери мындай көрүнөт:

| Формат | Кеңейтүү |
|--------|----------|
| Markdown | .md |
| Жөнөкөй текст | .txt |
- [x] Долбоорду жазуу
- [ ] Карап чыгуу

Абзацтар бош саптар менен бөлүнөт. Жалгыз сап которуу көпчүлүк ишке ашырууларда ошол эле абзацтын бөлүгү катары каралат; сапты мажбурлап которуу үчүн саптын аягына эки боштук коюңуз. Markdown'дун ичинде түз эле HTML да жазса болот. CommonMark буга уруксат берет, бирок GFM сыяктуу чөйрөлөр коопсуздук үчүн айрым тегдерди бөгөттөйт.

Markdown кайда колдонулат?

• Программалык камсыздоону иштеп чыгуу: README'лер, өзгөртүүлөр журналдары жана салым кошуу боюнча колдонмолор, ошондой эле GitHub жана GitLab сыяктуу платформалардагы маселелер жана кодду карап чыгуу комментарийлери.
• Техникалык документация: Markdown файлдарынан веб-сайттарды курган статикалык сайт генераторлору.
• Эскертме жазуу: көптөгөн эскертме тиркемелери жазууларды Markdown түрүндө сактайт же экспорттойт.
• Чат жана коомчулук платформалары: Reddit жана Discord сыяктуу платформалар Markdown'дун түрлөрүн колдонот.
• Жазуу жана басып чыгаруу: Pandoc сыяктуу куралдар менен бир Markdown булагынан HTML, PDF, DOCX жана EPUB түзүү.
• Жасалма интеллект куралдары: чат түрүндөгү ЖИ жардамчылары жоопторун көбүнчө Markdown менен форматташат.

Күчтүү жана алсыз жактары

Markdown'ду кайсы программалар ачат?

Markdown жөнөкөй текст болгондуктан, ал каалаган текст редакторунда, анын ичинде Notepad жана TextEdit'те да ачылат. Форматталган алдын ала көрүү үчүн Visual Studio Code'дун орнотулган Markdown алдын ала көрүүсүн же Obsidian, Typora сыяктуу атайын редакторлорду колдонсоңуз болот. GitHub жана GitLab репозиторийлердеги .md файлдарын автоматтык түрдө көрсөтөт. Ал эми Word Markdown'ду форматталган текст катары ачпайт, ошондуктан адегенде файлды конвертациялоо керек.

Көп кездешкен көйгөйлөр жана аларды чечүү

Тизме же аталыш көрсөтүлбөйт

CommonMark аталыш белгисинен кийин боштукту талап кылат: ##Аталыш эмес, ## Аталыш. Абзацтан кийин келген тизме да туура көрсөтүлүшү үчүн көбүнчө ортосунда бош сап керек.

Саптар бириге берет

Жалгыз сап которуу абзацты бөлбөйт. Жаңы абзац үчүн бош сап калтырыңыз же абзацтын ичинде сапты которуу үчүн саптын аягына эки боштук коюңуз.

Таблица бир платформада иштейт, башкасында иштебейт

Таблицалар Грубердин түп нуска Markdown'унун да, CommonMark'тын өзөгүнүн да бөлүгү эмес; алар GFM сыяктуу кеңейтүүлөрдөн келет. Максаттуу платформа кайсы түрдү колдой турганын текшериңиз.

Сан менен башталган абзац номерленген тизмеге айланат

«2024. Абдан бош эмес жыл болду» сыяктуу сап сандар жана чекит менен башталгандыктан, тизме катары талданышы мүмкүн. Мунун алдын алуу үчүн чекитти тескери сызык менен экранга алыңыз (2024\.).

Markdown файлдарды конвертациялоо боюнча кеңештер

Биздин конвертерде Markdown файлдары биздин серверге жүктөлүп, 30 мүнөттүн ичинде өчүрүлөт. Окуу үчүн биз CommonMark жана GitHub стилиндеги кеңейтүүлөр (таблицалар, тапшырмалар тизмелери, сноскалар, автошилтемелер) менен Markdig китепканасын колдонобуз.

• Markdown'дон PDF'ке жана Markdown'дон Word'го конвертациялоо аталыштарды, тизмелерди, код блокторун, цитаталарды жана чектелген таблицаларды сактайт. Тапшырмалар тизмесинин белгилөө кутучалары Word'до жана PDF'те көрүнүп турушу үчүн ☑ жана ☐ белгилерине айландырылат. Текст демейки боюнча 12 pt серифтүү шрифт менен, код блоктору болсо бирдей туурасы бар шрифт менен терилет.
• Markdown'дон HTML'ге конвертациялоо README'ни белги коддоосу жарыяланган өз алдынча веб-баракка айлантат.
• Тескери багытта Word'дон Markdown'го, HTML'ден Markdown'го жана PDF'тен Markdown'го конвертациялоо GitHub менен шайкеш Markdown түзөт: аталыштар, калың жана курсив текст, тизмелер, таблицалар, шилтемелер, код блоктору жана цитаталар сакталат; шрифттер, түстөр жана барак макети алынып салынат. Баш сабы жок таблицаларда биринчи сап баш сап болуп калат, анткени GFM таблицалары аны талап кылат. «1. Пункт» сыяктуу сан менен башталган жөнөкөй абзацтар кокустан тизмеге айланбашы үчүн экранга алынат. Файл BOM'суз UTF-8 катары сакталат.

Көп берилүүчү суроолор

MD файлын кантип ачса болот?

Аны каалаган текст редактору ачат. Форматталган түрүндө көрүү үчүн Visual Studio Code'дун алдын ала көрүүсүн же Markdown редакторун колдонуңуз; Word'до окугуңуз келсе, аны DOCX'ке конвертациялаңыз.

CommonMark менен GitHub Flavored Markdown'дун айырмасы эмнеде?

CommonMark Markdown'дун негизги синтаксисин так эрежелер менен аныктайт. GFM CommonMark'тын үстүнө таблицалар, тапшырмалар тизмелери, сызылган текст жана кеңейтилген автошилтемелер сыяктуу кеңейтүүлөрдү кошкон анын кеңейтилген топтому.

Markdown'да таблица түзсө болобу?

Ооба, GFM сыяктуу кеңейтүүлөр менен тик сызыктар жана дефистер аркылуу жөнөкөй таблицаларды жазсаңыз болот. Бириктирилген уячалар сыяктуу татаал түзүлүштөр үчүн HTML таблицасын колдонуңуз же документти Word'до даярдаңыз.

Markdown менен HTML'дин айырмасы эмнеде?

Markdown HTML'ге конвертациялануу үчүн иштелип чыккан жөнөкөйүрөөк жазуу форматы. Ал HTML туюнта алгандын баарын туюнта албайт, бирок анын чийки түрү алда канча окулуучу. Керек болгондо Markdown'дун ичинде HTML да жаза берсеңиз болот.

Markdown'дун расмий стандарты барбы?

Грубердин түп нуска сүрөттөмөсү расмий спецификация эмес. Бүгүн эң кеңири кабыл алынган так аныктама CommonMark, ал эми text/markdown медиа түрү 2016-жылдын мартында RFC 7763 менен катталган.

Булактар

• John Gruber, Daring Fireball: Markdown
• CommonMark Spec (версиялардын тарыхы)
• GitHub Flavored Markdown Spec
• IETF RFC 7763: The text/markdown Media Type (2016-жылдын марты)
• IETF RFC 7764: Guidance on Markdown
• Wikipedia: Markdown (тарыхы, экинчилик булак)
• Markdig: .NET үчүн CommonMark менен шайкеш Markdown процессору