{"canonical_url":"https://engineer.company/uk/glossary/markdown/","content_markdown":"# Markdown\n\n## Що це таке\n\nMarkdown — це спосіб писати документ як звичайний текстовий файл, у якому кілька\nнабраних умовностей підказують конвертеру, який HTML створити: зірочки довкола\nслова для виділення, знак решітки перед заголовком, дефіс перед кожним пунктом\nсписку і квадратні дужки з круглими після них для посилання. Назва охоплює і\nсинтаксис, і програму, у вигляді якої він з'явився, файли зазвичай мають\nрозширення `.md` або `.markdown`, а діалекти, що з нього виросли, серед них\nCommonMark і GitHub Flavored Markdown (GFM), теж звуться Markdown.\n\nДжон Грубер створив його у 2004 році разом з Аароном Шварцом і написав перший\nконвертер на Perl; останній випуск, Markdown 1.0.1, датовано 17 грудня 2004\nроку. Головною метою він називав читабельність: документ Markdown має бути\nпридатним до публікації як є, звичайним текстом, і не виглядати так, ніби його\nрозмітили тегами чи інструкціями форматування. Найбільше на синтаксис, за його\nсловами, вплинуло те, як люди вже оформлювали листи електронної пошти у\nзвичайному тексті. Усе, чого синтаксис не охоплює, пишуть як HTML посеред\nтексту, без перемикачів чи розділювачів, бо в його баченні Markdown — формат для\nписьма, а HTML — формат для публікації.\n\nКілька рядків показують майже все:\n\n```markdown\nПереїзд зайняв **один вечір**, у три кроки:\n\n- зупинити записи\n- скопіювати дані за допомогою `pg_dump`\n- спрямувати [застосунок](https://example.com/app/) на новий хост\n```\n\nКонвертер перетворює це на абзац з елементом `strong`, список із трьох пунктів,\nфрагмент коду й посилання, а джерело й далі читається як нотатка, яку хтось\nпросто набрав.\n\n## Чому це важливо\n\nДжерело і є документом, а звичайний текст переживає кожен інструмент довкола\nнього. Файл Markdown відкривається в будь-якому редакторі, порівнюється рядок за\nрядком у системі контролю версій і зручно переглядається в pull request. Жоден\nпостачальник не може скасувати цей формат, а перенесення масиву текстів з однієї\nсистеми в іншу зводиться до копіювання файлів.\n\nЦіна — неоднозначність. Проєкт CommonMark каже про це прямо: опис Грубера не\nзадає синтаксис однозначно, а його скрипт мав помилки й востаннє оновлювався в\nгрудні 2004 року, тож до 2014 року існували десятки реалізацій, і кожна\nзаповнювала прогалини по-своєму. Приклад проєкту — документ, який на вікі GitHub\nвиглядає одним чином, а після перетворення в DocBook за допомогою Pandoc —\nіншим. А оскільки в Markdown немає синтаксичних помилок, розбіжність виявляється\nлише тоді, коли хтось дивиться на результат. Проєкт радить Babelmark 3, що\nпроганяє той самий вхідний текст через понад двадцять реалізацій, щоб побачити,\nчи вони узгоджуються.\n\nCommonMark, започаткований у 2014 році, відповідає специфікацією, яку написав\nДжон Макфарлейн: кожне правило в ній прив'язано до прикладів вхідного тексту й\nточного HTML, який з нього має вийти, — 652 приклади у версії 0.31.2 від 28\nсічня 2024 року. GitHub визначає свій діалект, GFM, як строгу надмножину\nCommonMark і додає таблиці, списки завдань, закреслення, розширені автопосилання\nта фільтр, що знешкоджує короткий список сирих HTML-тегів. Конвертер Markdown у\nHugo, Goldmark, відповідає специфікації CommonMark і сумісний з GFM.\n\nMarkdown має й власну назву в мережі. З березня 2016 року RFC 7763 реєструє тип\n`text/markdown` для всієї родини синтаксисів з обов'язковим параметром `charset`\nі необов'язковим `variant`, який називає діалект файлу.\n\n## Як це виглядає на практиці\n\nНаписані вручну сторінки цього сайту — це Markdown, розкладений шаблонами Go.\n[Сторінка подяк називає обидва](/uk/credits/) серед інструментів, якими зроблено\nсторінки, поруч із Hugo, генератором статичних сайтів. Вона ж називає\nmarkdownlint серед лінтерів, що тримають вихідний код у порядку, а в\nобов'язкових перевірках якості кожне зауваження вважається помилкою, а не\nпопередженням.\n\n[Сторінка про готовність до ШІ-агентів](/uk/ai-ready/) показує формат з іншого\nбоку: кожна сторінка тут має Markdown-двійника за тією самою адресою, до якого\nможна дістатися, додавши `index.md` або попросивши `text/markdown`, а під час\nзбірки кожного двійника перевіряють на залишки розмітки, і збірка зупиняє\nпублікацію, коли якийсь двійник цієї перевірки не проходить. Двійник сторінки про готовність до ШІ-агентів — за один запит:\n\n```sh\ncurl -sL https://engineer.company/uk/ai-ready/index.md\n```\n\n[Близько 50 000 слів документації до програмного забезпечення](/uk/portfolio/wrote-50000-words-of-software-documentation/)\nлягли в Markdown у GitHub, Craft і Confluence, і значну частину з них написано\nвручну. Ці тексти описували архітектуру, процеси й практичні інструкції на\nзапитання, які люди ставили раз у раз, зберігалися під контролем версій так, щоб\nїх легко було знайти, і допомогли новачкам швидше входити в роботу.\n\n## Де виникають проблеми\n\n**Замість жирного тексту виводяться зірочки.** Читач бачить по дві зірочки з\nобох боків слова, яке мало бути жирним, а всі перевірки лишаються зеленими, бо\nHTML коректний і посилання працюють. CommonMark відкриває виділення лише на\nлівофланговій послідовності зірочок, а послідовність, після якої стоїть\nрозділовий знак, як-от квадратна дужка посилання, зараховується лише тоді, коли\nперед нею пробіл або розділовий знак. Літера перед зірочками залишає їх\nбуквальними, і так само діє все, що шаблонізатор ставить туди до розбору\nMarkdown: Hugo замінює шорткод заповнювачем із літер і цифр. Шаблон\nMarkdown-двійників цього сайту фіксує, що коли прибрали пробіл між шорткодом і\nжирним текстом поруч, жирне виділення зламалося на 60 пунктах списку трьома\nмовами. Залишайте пробіл і перевіряйте показану сторінку, а не джерело; серед\nобов'язкових перевірок цього сайту є та, що читає зібраний HTML у пошуках\nMarkdown, який дійшов до читача як розділові знаки.\n\n**Той самий файл показують по-різному.** Вкладений список в одній системі стає\nпласким, а в іншій лишається вкладеним, або решітка на початку рядка в одному\nконвертері робить заголовок, а в іншому лишається текстом, і ніхто про це не\nповідомляє, бо в Markdown немає синтаксичних помилок, про які можна повідомити.\nПричина — різниця діалектів: два конвертери по-різному заповнюють одну з\nпервісних прогалин. Назвіть діалект, яким пише проєкт, здебільшого CommonMark\nабо GFM, використовуйте лінтер, що тримає файли в його межах, і проганяйте\nсумнівний текст через кілька реалізацій, перш ніж на нього покладатися.\n\n**Markdown-версія сторінки містить HTML.** Читач текстової версії натрапляє на\nсирі елементи `svg` або на номер телефону, що починається з числового посилання\nна символ там, де мав бути знак плюс. Компонент, який виводить HTML для\nвебсторінки, виводить той самий HTML і в усі інші формати, якщо йому не вказати\nінакше; Hugo шукає шаблон шорткода для кожного вихідного формату окремо й\nповертається до HTML-шаблону. Шаблони шорткодів цього сайту фіксують обидва\nвипадки, 49 сирих елементів `svg` у Markdown-версії сторінки подяк і номер з\nконтактної сторінки, екранований для HTML, і тепер кожен шорткод, що пише хоч\nякусь розмітку, має власний шаблон для Markdown. Обов'язкові перевірки також\nстежать, щоб Markdown-двійники не містили сирого HTML і HTML-сутностей,\nпропускаючи код.\n\n**Сирий HTML зникає зі сторінки.** Блоку HTML, записаного в Markdown, немає на\nзібраній сторінці, хоча джерело виглядає гаразд. Синтаксис Грубера дозволяє HTML\nбудь-де в тексті, але конвертер має право від нього відмовитися: налаштування\n`unsafe` для Goldmark у Hugo типово вимкнене, тож сирий HTML, змішаний з\nMarkdown, не відображається, а GFM екранує короткий список тегів, як-от `script`\nта `iframe`, щоб вони виводилися як текст. Натомість беріть те, що пропонує\nгенератор, у Hugo це шорткод або render hook, або вмикайте налаштування свідомо\nй погоджуйтеся з тим, що воно пропускає.\n\n**Лінтер пропускає те, що йому наказали не помічати.** Файл Markdown з поламаною\nструктурою проходить рев'ю, бо markdownlint мовчить. Правила, які мали б це\nвпіймати, вимкнули в конфігурації й не записали чому. Правила розробки цього\nсайту фіксують, що markdownlint колись мав конфігурацію в JSON із шістьма\nвимкненими правилами без коментарів, і коли ці шість виміряли, два з них\nприховували справжні дефекти. Записуйте причину біля кожного вимкненого правила\nу форматі, який вміщує коментар, щоб наступна людина могла з нею не погодитися.\n\n## Що почитати далі\n\n- [CommonMark Spec](https://spec.commonmark.org/) — специфікація, правило за\n  правилом, кожне прив'язане до прикладів вхідного тексту й HTML, який має з\n  нього вийти.\n- [CommonMark](https://commonmark.org/) — навіщо знадобилася специфікація, як\n  розійшлися реалізації і хто її веде.\n- [Markdown, by John Gruber](https://daringfireball.net/projects/markdown/) —\n  початковий опис, мета задуму і скрипт на Perl.\n- [Markdown: Syntax](https://daringfireball.net/projects/markdown/syntax) —\n  виклад синтаксису від самого Грубера, з правилом для HTML посеред тексту.\n- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) — діалект\n  GitHub як надмножина CommonMark, де позначено кожне розширення.\n- [RFC 7763: The text/markdown Media Type](https://www.rfc-editor.org/rfc/rfc7763)\n  — медіатип, його обов'язковий `charset` і параметр `variant`.\n\n\u003chttps://engineer.company/uk/glossary/markdown/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Звідки взявся Markdown, чому один файл показують по-різному, як CommonMark фіксує синтаксис і які помилки виводять зірочки як текст.","formats":{"gemtext":"https://engineer.company/uk/glossary/markdown/index.gmi","gopher":"https://engineer.company/uk/glossary/markdown/gophermap","html":"https://engineer.company/uk/glossary/markdown/","json":"https://engineer.company/uk/glossary/markdown/index.json","markdown":"https://engineer.company/uk/glossary/markdown/index.md","pdf":"https://engineer.company/uk/glossary/markdown/index.pdf"},"kind":"page","language":"uk","title":"Що таке Markdown?","url":"https://engineer.company/uk/glossary/markdown/","version":1}