Описание Markdown Extra

Опубликовано 1 Февраль 2013 - 20:55 пользователем biv

Markdown Extra

PHP Markdown Extra - это специальная версия PHP Markdown, реализующая некоторые функции, недоступные в настоящее время для стандартного синтаксиса Markdown. Вы можете скачать PHP Markdown Extra с домашней страницы PHP Markdown.

Этот документ объясняет изменения и дополнения в синтаксисе Markdown^{(на русском)}, реализованные в PHP Markdown Extra. Вы уже должны быть знакомы с документацией по синтаксису оригинального Markdown перед прочтением данного документа.

Встраивание HTML
Markdown внутри HTML-блоков
Специальные атрибуты
Огражденные блоки кода
Таблицы
Списки определений
Сноски
- Результат
Аббревиатуры
Выделение жирным и курсивом
Обратная косая черта

Встраивание HTML

С помощью Markdown вы можете вставлять HTML прямо в середине текста. Это очень полезно, когда вам нужны некоторые функции, не предусмотренные Markdown-синтаксисом, которые легко сделать с помощью HTML.

Но Markdown имеет серьезное ограничение, когда дело доходит до блочных элементов. Из документации Markdown-синтаксиса:

Блочные элементы HTML (например <div>, <table>, <pre>, <p> и т.д.) должны отделяться пустыми строками от окружающего их текста, причём, начальный и конечный тэг не должны отступать от начала строки.

Эти ограничения были отменены в PHP Markdown Extra и заменены двумя менее строгими:

Открывающий тег блочного элемента не должен иметь отступ более чем в три пробела. Любой тег с отступом больше этого значения будет рассматриваться как блок кода в соответствии со стандартными правилами Markdown.
Когда блочный элемент находится внутри списка, все содержимое должно иметь отступ с таким же количеством пробелов, как у списка. (Больший отступ не нанесет никакого вреда, пока первый открывающий тег не будет иметь слишком большой отступ. в этом случае текст будет восприниматься как блок кода - см. первое правило.)

Markdown внутри HTML-блоков

В обычном Markdown вы не могли использовать Markdown-текст внутри элемента <div>. Это происходило потому, что <div> - блочный элемент, и обычная Markdown-разметка этого не поддерживает.

PHP Markdown Extra дает вам возможность вставить текст в Markdown-формате внутри любого блочного тега. Вы можете сделать это путем добавления атрибута markdown со значением 1 в тег. Примерно как здесь:

<div markdown="1">
Это *действительно* markdown-текст.
</div>

Атрибут markdown="1" будет вырезаться, и содержимое тега <div> будет преобразовано из Markdown в HTML. Конечный результат будет выглядеть так:

<div>

<p>Это <em>действительно</em> markdown-текст.</p>

</div>

PHP Markdown Extra достаточно умен, чтобы применять правильное форматирование в зависимости от атрибута markdown в блочном элементе. Если вы примените атрибут markdown, например, к тегу <p>, то преобразуются лишь элементы внутристрочного уровня, то есть внутри его не сработают списки, цитаты и блоки кода.

Однако бывают случаи, когда и это не столь однозначно, например как здесь:

<table>
  <tr>
    <td markdown="1">Это *действительно* markdown-текст.</td>
  </tr>
</table>

Дело в том, что ячейки таблицы могут содержать как внутристрочные, так и блочные элементы. В подобных случаях PHP Markdown Extra будет считать, что данное содержимое внутристрочного уровня. Если вы хотите, чтобы содержимое воспринималось блочным элементом, то просто напишите markdown="block".

Специальные атрибуты

С помощью PHP Markdown Extra вы можете установить атрибуты id и class для определенных элементов. Например, поставить нужный id префикс в фигурных скобках после заголовка в конце строке. Пример:

Заголовок 1            {#header1}
===========

## Заголовок 2 ##      {#header2}

Следом вы можете создать ссылку на определенное место в документе, вот так:

[Ссылка на заголовок 1](#header1)

Чтобы добавить имя класса, которое может быть использовано в таблице стилей, используйте точку, как показано ниже:

## Сайт ##    {.main}

Классы и id могут быть объединены вместе, это делается так:

## Сайт ##    {.main .shine #the-site}

Специальные атрибуты могут быть использованы только с заголовками и огражденными блоками кода.

Огражденные блоки кода

PHP Markdown Extra версии 1.2 включает в себя синтаксис блоков кода без отступов. Огражденные блоки кода практически такие же, как и стандартные Markdown блоки кода. Их отличие состоит в том, что они выделяются не отступом, а ограждающей линией в начале и конце блока. Блок кода начинается со строки, содержащей от 3 и более символов тильда ~, и заканчивается первой встреченной линией с таким же количеством символов тильда ~. Пример:

Это вводный абзац:

~~~~~~~~~~~~~~~~~~~~~
а это одна линия кода
~~~~~~~~~~~~~~~~~~~~~

Огражденные блоки кода в отличие от блоков, выделяемых отступом, могут иметь пустые строки и в начале, и в конце:

~~~

пустая строка перед этой линией
пустая строка после этой линии

~~~

Стандартные блоки кода не могут быть использованы сразу же после списка, потому что отступы списка имеют больший приоритет; огражденные блоки кода не имеют таких ограничений:

1.  Элемент списка

    Это не блок кода, отделяемый отступом, это второй
    абзац этого пункта в списке

~~~~
Это огражденный тильдами блок кода
~~~~

Огороженные блоки кода также идеально подходят, если вам нужно вставить какой-либо код в редактор, который не имеет команды для увеличения отступа в блоке текста. Примером может послужить текстовое поле в вашем веб-браузере.

Также вы можете указать имя класса, который будет применяться для блока кода. Это полезно, если вы хотите, чтобы у блоков кода был разный стиль, в зависимости от языка. Или вы можете использовать его, чтобы сообщить скриптам синтаксической подсветки, какой синтаксис использовать.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .html
<p>paragraph <b>emphasis</b>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Имя класса помещается в конце первого ограждения. Перед классом ставится точка. Вы также можете использовать специальные атрибуты:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.html #example-1}
<p>paragraph <b>emphasis</b>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

В выходном HTML атрибуты блока кода устанавливаются тегу code. Если вы хотите, чтобы они устанавливались тегу pre, то задайте константе MARKDOWN_CODE_ATTR_ON_PRE значение true.

Таблицы

PHP Markdown Extra имеет свой собственный синтаксис для простых таблиц. “Простая” таблица выглядит так:

Первый Заголовок  | Второй Заголовок
----------------- | -----------------
Содержимое Ячейки | Содержимое Ячейки
Содержимое Ячейки | Содержимое Ячейки

Первая строка содержит заголовки столбцов; вторая строка содержит обязательную разделительную линию между заголовками и содержимым; каждая следующая строка - это строка в таблице. Столбцы всегда отделены друг от друга символом вертикальной черты (|). После конвертации в HTML результат будет такой:

<table>
<thead>
<tr>
  <th>Первый Заголовок</th>
  <th>Второй Заголовок</th>
</tr>
</thead>
<tbody>
<tr>
  <td>Содержимое Ячейки</td>
  <td>Содержимое Ячейки</td>
</tr>
<tr>
  <td>Содержимое Ячейки</td>
  <td>Содержимое Ячейки</td>
</tr>
</tbody>
</table>

Если хотите, вы можете добавить вертикальную черту в конце и начале для каждой строки таблицы. Используйте форму записи, которая вам больше нравится. В качестве иллюстрации, дает тот же результат, что и таблица выше:

| Первый Заголовок  | Второй Заголовок  |
| ----------------- | ----------------- |
| Содержимое Ячейки | Содержимое Ячейки |
| Содержимое Ячейки | Содержимое Ячейки |

Примечание: Таблице нужна, по крайней мере, одна вертикальная черта на каждой строке для того, чтобы PHP Markdown Extra разобрал её правильно. Это означает, что единственный способ создать одноколоночную таблицу - это добавить вертикальную черту в конец или начало строки, или с обеих сторон сразу.

Вы можете указать выравнивание для каждого столбца, добавив двоеточия к разделительным линиям. Двоеточие в левой части разделительной линии создаст колонку с выравниванием по левому краю; двоеточие с правой стороны линии сделает столбец, выравненный по правому краю; двоеточие с обеих сторон означает, что столбец будет выравнен по центру.

| Предмет   | Цена  |
| --------- | -----:|
| Компьютер | $1600 |
| Телефон   |   $12 |
| Трубка    |    $1 |

HTML-атрибут align будет применяться к каждой ячейке соответствующего столбца.

Вы можете применить внутристрочное форматирование к содержимому каждой ячейки, используя обычный Markdown-синтаксис:

| Имя функции   | Описание                           |
| ------------- | ---------------------------------- |
| `help()`      | Отображение окна со справкой       |
| `destroy()`   | **Уничтожение вашего компьютера!** |

Списки определений

В PHP Markdown Extra реализованы списки определений. Списки определений состоят из терминов и из определений этих терминов, также как в словарях.

Простой список определений в PHP Markdown Extra состоит из строки термина и строки с последующим двоеточием и определением для этого термина.

Яблоко
:   Плод яблони, который употребляется в пищу в свежем
    виде, служит сырьём в кулинарии и для приготовления
    напитков. 

Апельсин
:   Плод апельсинного дерева, родом из Китая.

Термин должен быть отделен от предыдущего определения с помощью пустой строки. Определения могут располагаться на нескольких строках, в этом случае они должны иметь отступ. Но в принципе это необязательно: если вы хотите, немного полениться, то про создание отступа у определения, распространяющегося на нескольких строках, можно забыть - это все равно будет работать:

Яблоко
:   Плод яблони, который употребляется в пищу в свежем
виде, служит сырьём в кулинарии и для приготовления
напитков.

Апельсин
:   Плод апельсинного дерева, родом из Китая.

Каждый из предыдущих списков определений даст одинаковый HTML-результат:

<dl>
<dt>Яблоко</dt>
<dd>Плод яблони, который употребляется в пищу в свежем
виде, служит сырьём в кулинарии и для приготовления
напитков.</dd>

<dt>Апельсин</dt>
<dd>Плод апельсинного дерева, родом из Китая.</dd>
</dl>

Двоеточия в качестве маркера определения обычно располагают с левого края от него, однако может быть отступ в три пробела между ними. Маркеры определения должны сопровождаться одним или несколькими пробелами или табуляцией.

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

Яблоко
:   Плод яблони, который употребляется в пищу в свежем
    виде, служит сырьём в кулинарии и для приготовления
    напитков.
:   Официально зарегистрированная социал-либеральная 
политическая партия современной России.

Апельсин
:   Плод апельсинного дерева, родом из Китая.

Вы также можете ассоциировать несколько терминов с одним определением:

Термин 1
Термин 2
:   Определение а

Термин 3
:   Определение б

Если перед определением есть пустая строка, PHP Markdown Extra обернёт определение тегом <p> в HTML-выводе. Например, это:

Яблоко

:   Плод яблони, который употребляется в пищу в свежем
    виде, служит сырьём в кулинарии и для приготовления
    напитков.

Апельсин

:   Плод апельсинного дерева, родом из Китая.

превратится в следующее:

<dl>
<dt>Яблоко</dt>
<dd>
<p>Плод яблони, который употребляется в пищу в свежем
виде, служит сырьём в кулинарии и для приготовления
напитков.</p>
</dd>

<dt>Апельсин</dt>
<dd>
<p>Плод апельсинного дерева, родом из Китая.</p>
</dd>
</dl>

Так же, как обычные элементы списка, определение может содержать несколько абзацев и включать в себя другие блочные элементы, такие как цитаты, блоки кода, списки и даже другие списки определений.

Термин 1

:   Это определение с двумя абзацами. Но чтобы вы 
    поняли, откуда возникает это превратное представление
    людей, порицающих наслаждение и восхваляющих 
    страдания, я раскрою перед вами всю картину и разъясню,
    что именно говорил этот человек, открывший истину, 
    которого я бы назвал зодчим счастливой жизни.

    Действительно, никто не отвергает, не презирает, не 
    избегает наслаждений только из-за того, что это 
    наслаждения, но лишь из-за того, что тех, кто не умеет
    разумно предаваться наслаждениям, постигают великие 
    страдания.

:   Это второе определение для термина 1, обернутое тегом `<p>`,
    так как есть пустая строка перед ним.

Термин 2

:   Это определение содержит блок кода, цитату и список.

        блок кода.

    > цитата
    > в две линии.

    1.  первый пункт списка
    2.  второй пункт списка

Сноски

Сноска состоит из двух составных частей:

маркер в тексте, который станет надстрочным числом;
текст сноски, который будет помещен в список сносок в конце страницы.

Сноска выглядит следующим образом:

Это некоторый текст со сноской.[^1]

[^1]: А это сама сноска.

Текст сноски может находиться в любом месте документа, однако сноски всегда будут перечислены в том порядке, в каком они связаны в тексте. Обратите внимание, что вы не можете создать два маркера на один и тот же текст сноски. Если вы попытаетесь это сделать, то второй маркер сноски станет простым текстом.

Каждая сноска должна иметь уникальное имя. Это имя будет использоваться для связи ссылки на сноску и текста сноски, но оно никак не влияет на нумерацию сносок. Имена могут содержать любой символ, допустимый в рамках атрибута id в HTML.

Сноски могут содержать блочные элементы, то есть вы можете разместить несколько абзацев, списков, цитат и тому подобное. Это работает так же, как у элементов списка: просто отступ в следующих пунктах должен начинаться с четырех пробелов:

Это некоторый текст со сноской.[^1]

[^1]: А это сама сноска.

    Это второй абзац сноски.

Если вы хотите, чтобы это выглядело лучше, Вы можете оставить первую линию текста сноски пустой и поместить первый абзац чуть ниже:

[^1]:
    А это сама сноска.

    Это второй абзац сноски.

Результат

Не секрет, что один формат разметки сноски не может удовлетворить всех. В будущей версии может появиться программный интерфейс, позволяющий использовать различные разметки, которые будут созданы. Но на сегодняшний день это выглядит, как описано на сайте Daring Fireball (с небольшими изменениями).
Ниже вывод из первого примера:

<p>Это некоторый текст со сноской.
   <sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup></p>

<div class="footnotes">
<hr />
<ol>

<li id="fn:1">
<p>А это сама сноска.
   <a href="#fnref:1" rev="footnote">&#8617;</a></p>
</li>

</ol>
</div>

Немного загадочно, но в браузере это будет выглядеть следующим образом:

Это некоторый текст со сноской.¹

А это сама сноска. ↩

Атрибуты rel и rev в ссылках выражают отношение, которое они имеют со связанными с ними элементами. Маркер ссылается на сноску (поэтому rel="footnote"), а сноска ссылается на маркер (поэтому rev="footnote"). Эти атрибуты могут быть использованы для стилизации элементов посредством создания CSS-правил:

a[rel="footnote"]
a[rev="footnote"]

Вы также можете настроить атрибуты class и title для сносок и их маркеров. Существует четыре настраиваемых константы для этого в файле markdown.php. В значениях этих констант любое вхождение %% будет заменено на соответствующий номер сноски. Например, вы можете использовать:

define( 'MARKDOWN_FN_LINK_TITLE', "Go to footnote %%." );

Аббревиатуры

В PHP Markdown Extra добавлена поддержка аббревиатур (HTML-тег <abbr>). Как это работает? Довольно просто: создать расшифровку аббревиатуры, например, что-то вроде этого:

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

потом где-либо в документе написать текст, например, такой:

The HTML specification
is maintained by the W3C.

и любой экземпляр из этих слов в тексте преобразуется:

The <abbr title="Hyper Text Markup Language">HTML</abbr> specification
is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.

Аббревиатура чувствительна к регистру и будет охватывать все вхождения слова. Аббревиатура также может иметь пустое определение, в таком случае тег <abbr> будет добавлен в текст, но атрибут title будет отсутствовать.

Operation Tigra Genesis is going well.

*[Tigra Genesis]:

Расшифровка аббревиатуры может находиться в любом месте документа. В итоговой странице она будет вырезана.

Выделение жирным и курсивом

Правила для выделения курсивом незначительно отличаются от оригинального синтаксиса Markdown. В настоящее время PHP Markdown Extra подчеркивания в середине слова рассматривает как обычные символы. Курсив с помощью символа подчеркивания работает только для целых слов. Если вам нужно выделить курсивом лишь часть слова, это все еще возможно с помощью символа звездочки.

Для примера:

Пожалуйста, откройте папку "секрет_волшебного_ящика".

PHP Markdown Extra не будет конвертировать подчеркивания в курсив, потому что они находятся в середине слова. HTML-вывод будет выглядеть следующим образом:

<p>Пожалуйста, откройте папку "секрет_волшебного_ящика".</p>

Курсив при помощи подчеркиваний по-прежнему работает, пока вы выделяете целые слова, подобно этому:

Мне нравится, когда ты говоришь _я люблю тебя_.

Это же относится к выделению жирным: с PHP Markdown Extra вы больше не можете установить выделение жирным в середине слова с помощью подчеркивания, вы должны это делать с помощью звездочек.

Обратная косая черта

В PHP Markdown Extra добавляется двоеточие (:) и вертикальная черта (|) в список символов, которые в некоторых случаях нужно экранировать с помощью обратного слеша. Этим вы можете предотвратить запуск списка определений или таблицы.

Перевод: Igor V Belousov <igor@belousovv.ru>

Оригинал на английском http://michelf.ca/projects/php-markdown/extra/