Опис Markdown Extra
PHP Markdown Extra - це спеціальна версія PHP Markdown, що реалізує деякі функції, недоступні для стандартного синтаксису Markdown. Ви можете завантажити PHP Markdown Extra з домашньої сторінки PHP Markdown.
Цей документ пояснює зміни та доповнення в синтаксисі Markdown (українською), реалізовані в PHP Markdown Extra. Ви вже повинні бути знайомі з документацією синтаксису оригінального Markdown перед прочитанням цього документа.
Вбудовування HTML
За допомогою Markdown можна вставляти HTML прямо в середині тексту. Це дуже корисно, коли вам потрібні деякі функції, які не передбачені Markdown-синтаксисом, які легко зробити за допомогою HTML.
Але Markdown має серйозне обмеження, коли справа доходить до блокових елементів. З документації Markdown-синтаксису:
Блокові елементи HTML (наприклад
Потім ви можете створити посилання на певне місце в документі, ось так:
Щоб додати ім'я класу, яке можна використовувати у таблиці стилів, використовуйте точку, як показано нижче:
Ви також можете додати свої атрибути простим способом. Для цього вказується ім'я атрибута, знак рівності і слідом за ним значення (яке не може містити пробілів):
id , кілька імен класів, та інші атрибути користувача можуть бути об'єднані разом в одному блоці спеціальних атрибутів:
На даний час спеціальні атрибути можуть бути використані тільки з
Якщо зображення та посилання написані в стилі виносок, то блок поміщається в кінець рядка з міткою посилання або зображення:
Захищені блоки коду
Markdown Extra включає синтаксис блоків коду без відступів. Захищені блоки коду практично такі самі, як і блокикоду зі стандартним Markdown. Їхня відмінність полягає в тому, що вони виділяються не відступом, а лінією, що захищає, на початку і в кінці блоку. Блок коду починається з рядка, що містить від трьох і більше символів тильда
, і закінчується першою лінією з такою самою кількістю символів тильда
Також можна використовувати символ ` (машинописний зворотний апостроф) замість тильди:
Захищені блоки коду на відміну від блоків, що виділяються відступом, можуть мати порожні рядки і на початку, і наприкінці:
Стандартні блоки коду не можуть бути використані відразу після списку, тому що відступи списку мають більший пріоритет; захищені блоки коду не мають таких обмежень:
Також ви можете вказати ім'я класу, який буде використовуватись для блоку коду. Це корисно, якщо ви хочете, щоб блоки коду мали різний стиль, залежно від мови. Або ви можете використовувати його, щоб повідомити скриптам синтаксичного підсвічування, який синтаксис використовувати.
Ім'я класу міститься наприкінці першого огородження. Перед класом ставиться крапка. Ви також можете використовувати спеціальні атрибути:
У вихідному HTML атрибути блоку коду встановлюються тегу code. Якщо ви хочете, щоб вони встановлювалися тегу pre, то встановіть значення змінної code_attr_on_pre, що дорівнює true. Дивіться налаштування (англ.) для більш детальної інформації.
PHP Markdown Extra має власний синтаксис для простих таблиць. "Проста" таблиця виглядає так:
Перший рядок містить заголовки стовпців; другий рядок містить обов'язкову розділову лінію між заголовками та вмістом; кожен наступний рядок - це рядок у таблиці. Стовпці завжди відокремлені один від одного символом вертикальної межі (). Після конвертації в HTML результат буде такий:
Якщо хочете, ви можете додати вертикальну межу в кінці та на початку для кожного рядка таблиці. Використовуйте форму запису, яка вам більше подобається. Як ілюстрація, дає той самий результат, що і таблиця вище:
Примітка: Таблиці потрібна принаймні одна вертикальна риса на кожному рядку для того, щоб PHP Markdown Extra розібрав її правильно. Це означає, що єдиний спосіб створити одноколоночну таблицю - це додати вертикальну межу в кінець або початок рядка, або з обох боків відразу.
Ви можете вказати вирівнювання для кожного стовпця, додавши двокрапки до розділових ліній. Двокрапка в лівій частині розділової лінії створить колонку з вирівнюванням по лівому краю; двокрапка з правого боку лінії зробить стовпець, вирівняний праворуч; двокрапка з обох боків означає, що стовпець буде вирівняний по центру.
HTML-атрибут align буде застосовуватися до кожного осередку відповідного стовпця.
Ви можете застосувати внутрішньорядкове форматування до вмісту кожного осередку, використовуючи звичайний Markdown-синтаксис:
Списки визначень
У PHP Markdown Extra реалізовані списки визначень. Списки визначень складаються з термінів та визначень цих термінів, як у словниках.
Простий список визначень у PHP Markdown Extra складається з рядка терміна та рядка з наступною двокрапкою та визначенням для цього терміна.
Термін має бути відокремлений від попереднього визначення за допомогою порожнього рядка. Визначення можуть розташовуватись на кількох рядках, у цьому випадку вони повинні мати відступ. Але в принципі це необов'язково: якщо ви хочете, трохи полінуватися, то про створення відступу у визначення, що розповсюджується на кількох рядках, можна забути - це все одно працюватиме:
Кожен із попередніх списків визначень дасть однаковий HTML-результат:
Двокрапки як маркер визначення зазвичай розташовують з лівого краю від нього, проте може бути відступ в три пробіли між ними. Маркери визначення повинні супроводжуватися одним або декількома пробілами чи табуляцією.
Списки визначень можуть мати більш ніж одне визначення, пов'язане з одним терміном:
Ви також можете порівнювати кілька термінів з одним визначенням:
Якщо перед визначенням порожній рядок, PHP Markdown Extra оберне визначення тегом