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 жылы жасады, ал Аарон Шварц оның идеяларын талқылауға үлес қосты. Синтаксис қарапайым мәтіндік поштадағы әдеттерге (екпін үшін жұлдызшалар, тізім үшін дефистер) және setext пен Textile сияқты бұрынғы белгілеу тілдеріне сүйенді. Грубер өзінің Daring Fireball сайтында жариялаған Perl сценарийі Markdown.pl-дің 1.0.1 нұсқасы 2004 жылғы 17 желтоқсанмен белгіленген.

Алайда Грубердің сипаттамасы ресми спецификация емес, мысалдар арқылы түсіндіру еді. Екіұшты жағдайлар (кірістірілген тізімдер, шегініспен жазылған код блоктары, HTML араластыру) әр іске асыруды өз шешімін қабылдауға мәжбүр етті, және бір мәтін әр құралда әр түрлі нәтиже бере бастады. Бұған екі негізгі жауап болды:

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

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 қарапайым мәтін болғандықтан, ол кез келген мәтіндік редакторда, соның ішінде Блокнот пен 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 өңдегіші