Дополнительные возможности kramdown

Это третья статья о синтаксисе и возможностях kramdown. Способы добавления атрибутов (идентификаторов, классов и прочих), создание сносок и оглавления, а также немного о настройках kramdown.

Задание атрибутов в kramdown

Kramdown позволяет задавать элементам практически любые HTML-атрибуты. Для этого есть специальный тип разметки — список вложенных атрибутов. Список атрибутов задается в фигурных скобках, он содержит двоеточие и непосредственно данные.

Отличие от обычного markdown

Эта возможность не является частью стандартного markdown. Идея и синтаксис позаимствованы из основаны на правилах Maruku.

Списки вложенных атрибутов бывают 4 типов:

для задания id
для задания классов
для задания других атрибутов, парами ключ-значение
для ссылок на другой блок со вложенными атрибутами

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

Вот образец задания идентификатора для цитаты.

> Hello
{: #bq-id}

Hello

Классы также задаются с помощью CSS-нотации:

    ```
          Блок кода с заданным классом            
    ```
    {:.language-markdown}

Блок кода с заданным классом

Другие атрибуты задаются в стандартном виде ключ/значение, аналогично их заданию непосредственно внутри HTML-тега.Таким способом можно задавать классы, инлайновые стили, микроразметку, в общем, любые HTML-атрибуты. Можно задавать в одном блоке несколько атрибутов.

> Hello
{: .bq-with-class style="color:red" title="цитата с добавленным классом"}

Hello

Данные можно задавать только в виде ключ=”значение”. Нельзя задать просто data-attribute, надо указать значение атрибута — data-attribute=true.

Блоки с определением списка атрибутов:

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

Блоки с определением списка атрибутов имеют следующую структуру:

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

Название ссылки должно начинаться с буквы или числа, дальше опционально добавляются буквы, числа и дефисы.

> Hello
{: ref-name}

{:ref-name: style="color:green"}

Hello

Один идентификатор может ссылаться на другой:

> Hello
{: ref2}

{:ref2: ref-name .title title="reference"}
{:ref-name: style="color:green"}

Hello

Задание атрибутов строчным элементам

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

[ссылка](#heading1){: style="color:red"}
**выделенный текст**{: ref-name}
`строчный код`{: ref-name}

ссылка выделенный текст строчный код

Атрибуты для элементов списка задаются после маркеров.

* Элемент списка 1
* {: style="color:red"}Элемент списка 2
* {: ref-name}Элемент списка 3

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

Задание `ID` для заголовков

Для задания id заголовкам в kramdown существует и упрощенный синтаксис. На той же строке, что и заголовок, просто добавьте в фигурных скобках требуемый id в CSS-нотации, с хэшем. Вот так:

##### Заголовок с идентификатором {#zagolovok}

Заголовок с идентификатором

Этот сокращенный синтаксис используется только для задания идентификаторов и только для заголовков.

Автоматическая генерация `ID` для заголовков

Впрочем, заголовки kramdown может генерировать и автоматически.

За это отвечает опция auto_ids is set, по умолчанию она активирована. Работает она путем конвертации простого текста (при активации еще одной опции — auto_id_stripping используется только текст из текстовых элементов) следующим образом:

Все символы, кроме латинских букв, цифр, пробелов и дефисов удаляются
Все символы от начала строки до первой буквы удаляются
Все символы, кроме букв и цифр, заменяются дефисами
Все символы трансформируются в строчные
Если ничего не осталось, используется идентификатор section
Если идентификатор section существует, к нему добавляется порядковый номер после дефиса (сначала -1, затем -2 и так далее).

Примечание: опция auto_id_stripping будет удалена из версии 2.0, так как это станет поведением по умолчанию.

Вот образцы такой трансформации:

Заголовок	генерируемый ID	генерируемый ID с `auto_id_stripping`
# This is a header	this-is-a-header	this-is-a-header
## 12. Another one 1 here	another-one-1-here	another-one-1-here
### Do ^& it now	do–it-now	do–it-now
# Hallo	hallo	hallo
# Hallo	hallo-1	hallo-1
# 123456789	section	section
# Заголовок	section	section
# `<i>test</i>`	itesti	test

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

Отличие от обычного markdown

Автоматическая генерация ID не является частью стандартного markdown. Правила конвертации заголовка в ID основаны на правилах Pandoc.

Сгенерированные ID используются, если ID не были заданы вручную.

Автоматическая генерация оглавления

В kramdown есть возможность автоматически генерировать оглавление на основе заголовков с идентификаторами. Для того, чтобы вывести оглавление, достаточно просто добавить блок {:toc} к упорядоченному или неупорядоченному списку, после чего на месте списка будет в соответствующем виде (упорядоченном или нет) рендерится оглавление поста.

Чтобы исключить заголовок из оглавления, достаточно добавить к нему класс no_toc.


* Этот заголовок не попадет в оглавление
# Contents
{:.no_toc}

* Этот список будет заменен оглавлением, за вычетом заголовка "Contents",
к которому добавлен класс `no_toc`.
{:toc}

Для ограничения вложенности заголовков есть конфигурационная опция toc_levels, по умолчанию в оглавление попадают заголовки всех уровней (1..6).

Сноски

Сноски в kramdown работают аналогично реферальным ссылкам и их определениям. Нужно лишь поместить маркер сноски в нужном месте текста, а определение сноски можно задать где угодно в документе. Для задания определения сноски используется следующий синтаксис:

левая квадратная скобка [
за ней идет циркумфлекс ^
затем имя сноски и закрывающая правая квадратная скобка — [^ имя сноски]
далее двоеточие и содержание сноски [^ имя сноски]: содержание сноски

Маркер сноски задается еще проще:

левая квадратная скобка с циркумфлексом [^
имя сноски и закрывающая правая квадратная скобка

Это текст со сноской.[^1] Следующий текст со сноской.[^footnote]

Это текст со сноской.¹ Следующий текст со сноской.²

В сноски можно вкладывать любые блочные элементы — цитаты, блоки кода³ и т.д. Если сноска не используется в тексте, она не выводится.

[^1]: Обычная сноска.

[^footnote]:
    > Сноска с цитатой.

[^codeblock-note]:
    ```markdown
    А это код
    ```

Для сносок есть следующие опции:

Название опции	Настройка
`footnote_backlink`	Текст или символ, используемый в обратной ссылке сноски. По умолчанию это ‘&8617;’ — ↩
`footnote_nr`	Номер первой сноски, по умолчанию это 1.

Расширения

В kramdown есть три вида расширений:

Название расширения	Применение
comment	Создание комментариев.
nomarkdown	Вывод текста без обработки kramdown.
options	Задание опций для всего текста. Опция в тексте не может быть переписана, то есть нельзя парсить одну часть документа с одними опциями, а другую — с другими.

Расширения записываются в фигурных скобках. Для комментариев и отключения markdown используются открывающие и закрывающие теги — открывающий тег начинается с двух двоеточий, а закрывающий — с двоеточия и слэша. При задании опций закрывающий тег не используется, слэш ставится перед закрывающей фигурной скобкой.


{::comment}
Этот текст комментария будет полностью проигнорирован kramdown.
{:/comment}

{::nomarkdown}
>Этот текст будет выведен --- но не будет обработан kramdown
{:/nomarkdown}

{::options parse_block_html="true" /}
>Активация этой опции трансформирует три дефиса внутри `div` в тире:
<div>
"text --- text"
</div>

>Этот текст будет выведен --- но не будет обработан kramdown

Активация этой опции трансформирует три дефиса внутри div в тире:

“text — text”

Опции

Кроме опций для генерации заголовков, подсветки кода и сносок в kramdown есть и другие опции. Часть из них относится к конвертации в Latex, обработке математических данных и прочим специфическим вещам, остальные перечислю.

Название опции	Настройка
`entity_output`	Вывод сущностей в неизменном виде, в цифровом или в символическом. По умолчанию `as_char`.
`hard_wrap`	Интерпретирует разрывы строк буквально и вставляет на их месте теги `br`. По умолчанию — `true`.
`header_offset`	Изменяет парсинг заголовков, увеличивая или уменьшая уровень заголовка, в зависимости от значения — оно может быть и отрицательным числом. То есть если задать 1, заголовки `h2` будут выводится как заголовки `h3` и т.д. По умолчанию задан 0.
`line_width`	Изменяет ширину строки при выводе контента, по умолчанию она равна 72.
`link_defs`	Позволяет задать определения ссылок заранее, в виде хэша, ключами которого являются идентификаторы, а значениями — массивы из двух элементов (адрес и название ссылки).
`parse_block_html`	Включает обработку парсером kramdown содержимого блочных тегов html. По умолчанию отключена.
`parse_span_html`	То же, что и предыдущая опция, но для строчных тегов.
`remove_block_html_tags`	Удаляет блочные теги HTML.
`remove_span_html_tags`	Удаляет строчные теги HTML.

Обычная сноска. ↩
Сноска с цитатой.

↩
```
А это код
```
Сноски выводятся внизу документа и оборачиваются элементом div с классом fotnotes. ↩

Задание атрибутов в kramdown

Отличие от обычного markdown

Блоки с определением списка атрибутов:

Задание атрибутов строчным элементам

Задание ID для заголовков

Заголовок с идентификатором

Автоматическая генерация ID для заголовков

Отличие от обычного markdown

Автоматическая генерация оглавления

Сноски

Расширения

Опции

Серия статей: "Особенности синтаксиса kramdown":

Задание `ID` для заголовков

Автоматическая генерация `ID` для заголовков