Blog Posted by on 2-2-2025 in Взаємодія в роботі

Офіційний посібник із синтаксису Markdown мені здається надто довгим і не надто наочним, тому я склав короткий посібник, який допоможе вивчити або повторити синтаксис Маркдауна за годину.

Крім традиційного Маркдауна у розробників набув поширення доповнений та покращений варіант мови – Github Flavoured Markdown, скорочено GFM.

Основні відмінності GFM та чистого Маркдауна:

  • додали таблиці, яких не було в оригінальному Маркдауні;
  • додали альтернативний синтаксис для вставки блоків коду: тепер можна не ставити 4 пробіли перед кожним рядком коду, також можна явно вказати мову коду;
  • додали закреслений текст.
 # GitHub-Flavored Markdown ## Короткий посібник Абзаци створюються за допомогою порожнього рядка. Якщо навколо тексту зверху та знизу є порожні рядки, то текст перетворюється на абзац. Щоб зробити перенесення рядка замість абзацу, потрібно поставити два пробіли наприкінці попереднього рядка. Заголовки відзначаються дієзом `#` на початку рядка від одного до шести. Наприклад: # Заголовок першого рівня # ## Заголовок h2 ### Заголовок h3 #### Заголовок h4 ##### Заголовок h5 ###### Заголовок h6 У декоративних цілях заголовки можна "закривати" зі зворотного боку. ### Списки Для розмітки неупорядкованих списків можна використовувати або `*`, або `-`, або `+`: - елемент 1 - елемент 2 - елемент. Вкладені пункти створюються чотирма пробілами перед маркером пункту: * елемент 1 * елемент 2 * Вкладений елемент 2.1 * Вкладений елемент 2.2 * елемент. Упорядкований список: 1. елемент 1 2. елемент 2 1. вкладений 2. вкладений 3. елемент 3 4. Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.Насправді не важливо, як у коді пронумеровані пункти, головне, щоб перед елементом списку стояла цифра (будь-яка) з точкою. Можна зробити і так: 0. елемент 1 0. елемент 2 0. елемент 3 0. елемент 4 Список абзаців: * Раз абзац. Lorem ipsum dolor sit amet, consectetur adipisicing elit. * Два абзацу. Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing. * Три абзацу. Ea, quis, або nobis porro quos laborum minus sed fuga odio dolore natus quas cum enim necessitatibus magni provident non saepe sequi? Чотири абзац (чотири пробіли на початку або один tab). ### Цитати Цитати оформляються як у емейлах, за допомогою символу `>`. > Це є blockquote with two paragraphs. Lorem ipsum dolor sit amet, > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. > > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse > id sem consectetuer libero luctus adipiscing. Або більш лінивим способом, коли знак `>` ставиться перед кожним елементом цитати, абзац, заголовок або порожній рядок: > Це є blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. > > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing. У цитати можна поміщати що завгодно, зокрема вкладені цитати: > ## This is a header. > > 1. Це перший лист. > 2. Це являє собою другий список елементів. > > > Вкладена цитата. > > Here's some example code: > > return shell_exec("echo $input | $markdown_script"); ### Вихідний код У чистому Маркдауні блоки коду відбиваються 4 пробілами на початку кожного рядка. Але в GitHub-Flavored Markdown (скорочено GFM) є зручніший спосіб: ставимо по три апострофи (на букві Е) до і після коду. Можна також вказати мову вихідного коду. ` ` `html nav class="nav nav-primary"> ul>   0 коментарів Коментарі       Увійти     ul> nav> ` ` Найприємніше, що в коді не потрібно замінювати кутові дужки `< >` та амперсанд `&` на їх html-сутності. ### Інлайн код Для вставки коду всередині пропозицій потрібно укладати цей код апострофи (на букві Е). Приклад: ``. Якщо всередині коду є апостроф, код треба обрамити подвійними апострофами: ``There is a literal backtick (') here. ### Горизонтальна риса `hr` створюється трьома зірочками або трьома дефісами. *** ### Посилання Це вбудована [посилання з title елементом](http://example.com/link "Я посилання"). Це - [без title](http://example.com/link). А ось [приклад][1] [кількох][2] [посилань][id] з розміткою як у виносок. Прокатить і [короткий запис][ ] без вказівки id. [1]: http://example.com/ "Optional Title Here" [2]: http://example.com/some [id]: http://example.com/links (Optional Title Here) [короткий запис]: http://example.com/short Винесення довгих урлів із пропозиції сприяє збереженню читабельності вихідника. Виноски можна розташовувати у будь-якому місці документа. ### Emphasis Виділяти слова можна за допомогою `*` і `_`. Одним символ для похилого тексту, два символи для жирного тексту, три - для похилого та жирного одночасно. Наприклад, це _italic_ і це теж *italic*. А ось так уже __strong__, і так теж **strong**. А так ***жирний та похилий*** Одночасно. ### Закреслення У GFM додано закреслення тексту: дві тильди `~` до та після тексту. ~~Закреслено~~ ## Картинки Картинка без `alt` тексту ![](http://placehold.it/150x100) Картинка з альтом та тайтлом: ![Alt text](http://placehold.it/150x100 "Можна задати title") Запам'ятати просто: синтаксис як у посилань, тільки перед квадратною дужкою, що відкриває, ставиться знак оклику. Зображення «виноски»: ![Картинка][image1] ![Картинка][image2] ![Картинка][image3] [image1]: http://placehold.it/250x100 [image2]: http://placehold.it/200x100 [image3]: http://placehold.it/150x100 Картинки-посилання: [![Alt ​​text](http://placehold.it/150x100)](http://example.com/) ## Використання HTML усередині Markdown Можна змішувати Markdown та HTML. Якщо на якісь елементи потрібно поставити класи чи атрибути, сміливо використовуємо HTML: > Виділяти слова можна за допомогою * та _ . Наприклад, це italic і це теж italic. А ось так уже strong, і так теж strong. Можна і навпаки, всередині HTML-тегів використовувати Маркдаун. section class="someclass"> ### Приклад Маркдауна всередині HTML Виділяти слова можна за допомогою `*` і `_` . Наприклад, це _italic_ і це теж *italic*. А ось так уже __strong__, і так теж **strong**. section> ### Таблиці У чистому Маркдауні немає синтаксису для таблиць, а GFM є. First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell Для краси можна і з боків лінії намалювати: | First Header | Second Header | | ------------- | ------------- | | Content Cell | Content Cell | | Content Cell | Content Cell | Можна керувати вирівнюванням стовпців за допомогою двокрапки. | Left-Aligned | Center Aligned | Right Aligned | |:------------- |:---------------:| -------------: | | col 3 є | some wordy text | **$1600** | | col 2 є | centered | $12 | | zebra stripes | are neat | ~~$1~~ | Всередині таблиць можна використовувати посилання, похилий, жирний або закреслений текст. Для решти є звичайний HTML.

Короткий посібник з Маркдауна - Kozak

Щоб ваші приклади коду красиво виглядали та легко читалися, можете використовувати стандартне форматування Markdown за допомогою зворотних лапок. Такий підхід використовують GitHub, Slack, StackOverflow, Jira та майже всі форуми програмістів.

Щоб виділити код у рядку, як console.log можете використовувати одинарні зворотні лапки:

Для окремих прикладів коду використовуй потрійні зворотні лапки. Зверніть увагу, що зворотні лапки розміщуються на окремих рядках до та після твого коду.

``js console.log('hello, world!'); ```

В результаті вийде такий приклад коду (потрійні зворотні лапки видно не будуть):

console.log('hello, world!');

Короткий посібник з Маркдауна - Kozak

згорнути | вищенаведена ділянка для зручності процитована з повної довідки з редагування, розташованої за посиланням нижче.

Код та попередньо відформатований текст

Зробіть відступ у чотири пробіли, щоб створити ізольований блок .

printf("%d\n", 42); /* нагадайте, що було питання ? */

Ви також можете виділити текст і натиснути CTRL + K, щоб виділити його як код або зняти виділення.

Текст буде обернутий тегами та відображено з використанням моноширинного шрифту. Перші чотири пробіли будуть обрізані, але решта пробілів буде збережена.

Markdown та HTML ігноруються всередині блоку коду:

 Вам би це не сподобалося, якби воно не було в блоці коду.

Замість використання відступів, ви також можете виділяти код, обрамляючи його трьома і зворотними лапками або тильдами:

``` alert(false); ``` ~~~ alert(true); ~~~

Рядки коду

Щоб набрати фрагмент коду всередині рядка, використовуйте зворотні лапки:

Символ `$` - просто скорочення для `window.jQuery`.

(Зворотна лапка зазвичай знаходиться ліворуч угорі під клавішею Esc.)

Як і блоки коду, внутрішньорядкові фрагменти коду відображатимуться з використанням моноширинного шрифту. Markdown та HTML не працюватимуть усередині них. Зверніть увагу, що, на відміну від блоків коду, внутрішньорядкові фрагменти коду вимагають ручного екранування будь-якого HTML усередині них!

Якщо в самому коді знаходиться зворотна лапка, вам доведеться повторити її кілька разів як роздільник:

Ім'я ``Tuple`2`` є дійсним іменем типу .NET.

Розриви рядків

Закінчіть рядок 2 пробілами або додайте розрив рядка
:

Як сильно я люблю тебе? Чи не описати словами.

Курсив та напівжирний

*Це набрано курсивом*, і _це_ теж. **Це набрано напівжирним шрифтом**, і __це__ теж. Користуйтесь ***курсивом та жирним шрифтом одночасно*** тільки якщо ___необхідно___.

Ви також можете виділити текст і натиснути CTRL + I або CTRL + B щоб переключити текст похилого або напівжирного зображення відповідно.

Посилання

Основні посилання

Існують три способи вставки посилань. Останній читається найскладніше:

Ось вбудована посилання на [Google](https://www.google.com/). Ось посилання у вигляді виноски на [Google][1]. Ось посилання, що легко читається на [Yahoo!][yahoo]. [1]: https://www.google.com/ [yahoo]: https://www.yahoo.com/

Ви також можете виділити текст і натиснути CTRL + L, щоб зробити його посиланням, або натиснути CTRL + L за відсутності виділеного тексту для вставки посилання в поточну позицію.

Визначення посилань можуть з'являтися в будь-якому місці документа — перед або після того, де ви їх використовували. Ідентифікатори визначення посилань [1] та [yahoo] можуть бути будь-якими унікальними рядками. Вони нечутливі до регістру, тобто. [yahoo] = [YAHOO] .

Розширені посилання

Посилання можуть мати атрибут заголовка, що відображається під час наведення. Атрибути заголовка можна додавати; вони бувають корисними, якщо посилання саме по собі недостатньо інформативне і не повідомляє користувача про те, куди він буде перенаправлений.

Here's a . Не використовуйте "[«натисніть тут»][^2]". Завітайте [][web]. [^2]: https://www.w3.org/QA/Tips/noClickHere (Не використовуйте фразу «натисніть тут») [web]: https://ua.stackoverflow.com/ "Stack Overflow російською"

Можна також використовувати стандартний синтаксис HTML для гіперпосилань.

Чисті URL-адреси

Ми змінили аналізатор Markdown, і тепер він підтримує чисті URL-адреси (у більшості випадків, але не завжди – звертайте увагу на незвичайні символи в URL-адресах); вони автоматично будуть перетворені на посилання:

Я часто відвідую https://example.com.

Явно позначайте URL-адреси, поміщаючи їх у кутові дужки:

Ви бачили https://example.com>?

URL-адреси можуть бути або відносними або абсолютними

Заголовки

Підкресліть текст, щоб створити два заголовки верхнього рівня:

Заголовок 1 ======== Заголовок 2 --------

Ви також можете виділити текст та натиснути CTRL+H для перемикання різних стилів заголовків.

Кількість символів "=" або "-" не має значення; одного буде достатньо. Але при використанні більшої кількості символів заголовки буде простіше знайти в основному тексті.

Використовуйте символ # для позначення рівнів заголовків:

# Заголовок 1 # ## Заголовок 2 ## ### Заголовок 3 ###

Закриваючі символи # не є обов'язковими.

Горизонтальні лінії

Горизонтальна лінія

вставляється трьома або більше дефісами, зірочками або підкресленнями поспіль:

Ви також можете натиснути CTRL + R, щоб вставити горизонтальну лінію.

Правило №1 --- Правило №2 ******* Правило №3 ___

Також можна використовувати пробіли між символами:

Ви також можете натиснути CTRL + R, щоб вставити горизонтальну лінію.

Прості списки

- Використовуйте знак мінуса для маркування елементів + Або знак плюс * Або зірочку
1. Нумеровані списки прості 2. Markdown може відстежувати нумерацію списку 7. Таким чином, це буде елемент №3.

Ви також можете виділити текст і натиснути CTRL+U або CTRL+O щоб зробити маркований або нумерований список відповідно.

Список з подвійним міжрядковим інтервалом:

- Цей список оточений мітками 
. - Отже, тут буде додатковий пробіл між елементами

Розширені списки: Вкладення

Для того щоб помістити інший блок Markdown у список, просто зробіть відступ у чотири пробіли для кожного рівня вкладень:

1. Списки всередині списку: - Відступ у чотири пробіли. * відступ у вісім прогалин. - Знову чотири пробіли.
1. Списки всередині списку: - Відступ у чотири пробіли. * відступ у вісім прогалин. - Знову чотири пробіли. 2. Декілька пунктів у списку: Найкраще відокремлювати абзаци чотирма пробілами Можна залишати і три, але це може викликати проблеми при вкладенні інших об'єктів Залиште чотири. Ми додали додатковий пробіл у першому рядку для вирівнювання його з цими параграфами. У реальній ситуації ми можемо застосувати весь список для вирівнювання всіх елементів. Хоча цей параграф є частиною одного з елементів списку, він надто важкий для користувачів. Можливо, краще перенести вкладені параграфи вручну, як у випадку із двома попередніми. 3. Цитати всередині списку: > Пропустити рядок та > зробіть відступ для знаків > чотири пробіли. 4. Попередньо відформатований текст у списку: Пропустіть рядок і зробіть відступ у вісім прогалин. Для списку потрібно чотири пробіли і чотири для виконання блоку коду.

Прості цитати

Додайте значок > на початок рядка, щоб створити цитату.

> Синтаксис ґрунтується на методі, який використовується в роботі поштових програм. > для оформлення цитати. Вам не потрібно створювати новий рядок вручну > параграфів у цитаті, але якщо ви зробите це, то вони виглядатимуть набагато краще. Залежить від того, наскільки ви ліниві.

Ви також можете виділити текст і натиснути CTRL + Q, щоб помістити його в цитату або прибрати цитування.

Розширене цитування: Вкладення

Щоб помістити інші блоки Markdown у цитату, просто додайте > символ і пробіл після нього.

Щоб помістити інші блоки Markdown у цитату, просто додайте символ > і пробіл після нього:

> Символ `>` є обов'язковим на порожніх рядках. > створення єдиної цитати. > > Якщо прибрати додатковий символ `>` > в результаті вийде > дві окремі цитати.

Цитати всередині цитати:

> Стандартна цитата має відступ > > Вкладена цитата має занадто великий відступ > > > > Підтримується вкладеність будь-якої глибини.

Списки всередині цитати:

> - Список усередині цитати > - З символом > та пробілом перед ним > * додатковий список

Попередньо відформатований текст у цитаті:

> Відступ у п'ять прогалин. Перший > є частиною покажчика цитати.

Зображення

Зображення оформляються так само, як і посилання, але перед ними стоїть знак оклику:

![Вірний XHTML](https://w3.org/Icons/valid-xhtml10).

Ви також можете натиснути CTRL + G, щоб вставити зображення.

Слово у квадратних дужках – це alt-текст, який відображатиметься у браузері, якщо він не може завантажити картинку. Не забудьте вказати інформативний alt-текст для програм, які читають з екрана.

Як і посилання, картинки підтримують синтаксис виносок та заголовки:

Ця сторінка містить позначку про ![вірним XHTML][]. [Галочка]: https://w3.org/Icons/valid-xhtml10 «Над чим ти смієшся?»

Увага: Markdown не підтримує скорочений синтаксис для зображень:

Неправильне ![форматування].

Однак ви можете використовувати трохи більш розширену версію прихованих імен посилань:

Ця ![Галочка][] працює.

Ім'я посилання також використовується як текст alt.

Доступний стандартний синтаксис HTML для зображень, який дозволяє змінювати ширину та висоту зображення.

URL-адреси можуть бути або відносними або абсолютними

Вбудований HTML

Якщо потрібно реалізувати розмітку, яка не підтримується Markdown, використовуйте HTML. Зверніть увагу на те, що підтримується лише обмежене підмножина HTML!

Щоб перезавантажити комп'ютер, натисніть ctrl +alt+del.

Markdown не вноситиме зміни до HTML-коду на рівні рядків:

 Markdown тут працює *нормально*.

Блокові елементи HTML мають кілька обмежень:

  1. Їх слід відокремити від навколишнього тексту порожніми рядками.
  2. Початкові та кінцеві мітки зовнішнього елемента блоку не повинні мати відступів.
  3. Markdown не можна використовувати всередині блоків HTML-коду.
 Тут не можна використовувати Markdown.

Потрібна докладніша інформація?

Додатки Stack Exchange

Наступні розділи описують деякі додаткові можливості форматування тексту, які є частиною CommonMark.

Мітки

Для обговорення мітки на даному сайті, наприклад, використовуйте

всі питання з міткою [tag:слони], щоб дізнатися більше.

Мітка буде автоматично пов'язана з відповідною міткою сторінкою.

Спойлери

Щоб приховати деяку частину тексту і зробити її видимою, тільки коли користувач натисне на неї, використовуйте синтаксис цитування з додаванням знака оклику:

Наприкінці п'ятого епізоду з'ясовується, що >! він дійсно його батько.

Підсвічування синтаксису в коді

Для блоків коду використовуватиметься підсвічування синтаксису за допомогою highlight.js. У багатьох випадках мова підсвічування синтаксису автоматично визначиться на основі міток питання.

Щоб вручну вказати мову для блоку коду, виділеного межами, додайте мову в рядок з кордоном:

``` lang-js setTimeout(function() < alert("JavaScript"); >, 1000); ````

Ви можете використовувати один із підтримуваних кодів мови, наприклад lang-cpp або lang-sql, або вказати мітку, і тоді буде використовуватися мова підсвічування синтаксису, пов'язана з цією міткою.

Щоб вказати мову підсвічування синтаксису для всіх наступних блоків коду використовуйте:

Щоб вказати, що для цього блоку коду не потрібне підсвічування синтаксису, використовуйте:

Таблиці

| Заголовок | Ще заголовок | --------- | -------------- | | Перший | рядок | | Друга | рядок |

Вирівнювання

Ви можете задати вирівнювання стовпця таблиці додавши : у відповідну комірку розділової лінії. Символ : зліва зробить стовпець вирівняним ліворуч (за замовчуванням). Символ: справа зробить стовпець вирівняним праворуч.Додавання: з двох боків призведе до вирівнювання по центру.

| ліворуч | центром | праворуч | |:----- |:---------:| ------:| | Один | Два | Три |

Детальніше про синтаксис

  • Рядок заголовка обов'язковий, і за ним повинен слідувати рядок-розділювач з такою ж кількістю осередків
  • Осередки розділяються за допомогою символу вертикальної риси ( | )
  • Початкові та кінцеві вертикальні лінії є необов'язковими
  • Пробільні символи і – не потрібно вирівнювати візуально

Форматування коментарів

Коментарі підтримують лише курсив, напівжирний шрифт, код та кілька скорочень для посилань.

_курсив_ і **напівжирний** шрифт, вбудований код в одиночних лапках; та [основні посилання](https://example.com).

Підтримувані скорочення для посилань:

  • [meta] – посилання на Мету для поточного сайту; текст посилання повинен містити ім'я сайту (наприклад, "Super User Meta"). Не працює, якщо сайт немає Мети (або сайт сам є Метою).
  • [main] – як [Мета], лише навпаки.
  • [edit] – посилання на сторінку редагування повідомлення, якому адресовано коментар, наприклад /повідомлення//редагування. Текст посилання «редагування» (з урахуванням регістру).
  • [tag:tagname] та [meta-tag:tagname] — посилання на сторінку цієї позначки. Текст посилання містить ім'я мітки. meta-tag працює тільки на Меті
  • [help] , [help/on-topic] , [help/dont-ask] , [help/behavior] і [meta-help] – посилання на сторінки Довідкового Центру, що часто відвідуваються. Текст посилання «Довідка» (з урахуванням регістру). Усі посилання ведуть до основного сайту.
  • [tour] – Посилання на сторінку «Тур». Текст посилання «тур» (з урахуванням регістру).
  • [so], [pt.so], [su], [sf], [metase], [a51], [se] – посилання на заданий сайт. Текст посилання містить назву сайту.
  • [chat] – посилання на чат даного сайту, текст посилання – "Чат".
  • [ask] , [what you are asking] , [answer] – посилання на сторінку "Як запитувати" або "Як відповідати".
  • [code block] – посилання на сторінку довідки Markdown. Текст посилання блок коду.
  • [mcve], [mre], [reprex], [repro], [example] – посилання на сторінку /help/minimal-reproducible-example з текстом «мінімальний приклад, що відтворюється».
  • [щось.se] – посилання на щось.stackexchange.com, якщо сайт існує. Текст посилання містить назву сайту. Використовуйте [ubuntu.se] для Ask Ubuntu.

Відповіді у коментарях

Автор повідомлення завжди отримує повідомлення про ваш коментар. Якщо ви відповідаєте іншому коментатору, вкажіть його ім'я там: @ peter і @ PeterSmith повідомлять попереднього коментатора на ім'я “Peter Smith”.

Зазвичай достатньо згадати тільки ім'я учасника, на чий коментар ви відповідаєте, наприклад @ben або @marc. Однак іноді потрібне уточнення: якщо раніше в коментарях брали участь три особи на ім'я Бен, необхідно додати перший символ прізвища, наприклад, @ben m або @ben c . При відповіді на коментарі прогалини в іменах використовувати не можна, тому пишіть не @peter smith, а @peters або @petersmith.

Якщо у учасника, якому ви відповідаєте, відсутні дані про його справжнє ім'я та прізвище, просто введіть кілька символів його імені учасника, щоб було зрозуміло, до кого ви звертаєтесь. Мінімально потрібно 3 символи. Тому, якщо ви відповідаєте учаснику DeathKnight666, введіть @dea , @death або @deathknight .

Можна використовувати цей метод для надсилання повідомлення будь-якому редактору повідомлення або, за потреби, ♦ модератору, який закрив питання.