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

Ссылки

В kramdown поддерживается три вида ссылок: автоматические, строчные и реферальные.

1. Автоматические ссылки.

Это наиболее простая разновидность, для вставки такой ссылки достаточно заключить URL в угловые скобки. Какие-либо настройки для этого вида ссылок не предусмотрены.

>Это простая ссылка на домашнюю страницу: <http://prgssr.ru>.

Это простая ссылка на домашнюю страницу: http://prgssr.ru.

2. Строчные ссылки

Основная разновидность ссылок. Синтаксис строчных ссылок позволяет задавать текст внутри тега a, отличный от URL. В kramdown к ссылке также можно добавить атрибут title — он задается в кавычках через пробел после адреса.

>Это [ссылка](http://rubyforge.org) на страницу.
В [ссылке](http://prgssr.ru "главная страница") можно указать title.
Адрес ссылки также может содержать [пробелы](link with spaces.html)

Это ссылка на страницу.

В ссылке можно указать title.

3. Реферальные ссылки

Реферальные ссылки или ссылки на ссылки позволяют ссылаться на ярлык ссылки.

>Это [реферальная ссылка][linkid] на страницу. И [это]
[linkid] тоже ссылка. И [это][] и даже [это].

Это реферальная ссылка на страницу. И это тоже ссылка. И это и даже это.

Чтобы реферальные ссылки заработали, их надо задать. Для этого надо просто вставить их в текст в любом месте страницы. Идентификатор ссылки задается в квадратных скобках, после них ставится двоеточие. Идентификатор может быть и кириллическим.

[linkid]: http://prgssr.ru/ "Перейти на главную страницу"

[это]: http://prgssr.ru/ "Тупо нажать"

Изображения

Синтаксис для вставки изображений похож на синтаксис строчных ссылок. В начале идет восклицательный знак (!), затем в квадратных скобках атрибут alt, а после этого в круглых скобках URL изображения.

Адрес изображения можно также задать через реферал. Вот образец:

![Jekyll]
[Jekyll]: /images/jekyll.png "Джекилл"

Jekyll

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

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

Механизм задания аббревиатур похож на задание реферальных ссылок. Астериск (*), затем аббревиатура в квадратных скобках, за ними двоеточие и расшифровка. Однажды заданная аббревиатура работает во всем тексте.

Этот текст написан не на HTML, а с использованием другого языка!

*[другого языка]: kramdown

*[HTML]: HyperTextMarkupLanguage

Этот текст написан не на HTML, а с использованием другого языка!

Блоки кода

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

{: .language-markdown}
    Какой-то код.

    Это тот же блок кода.
^
    А это уже другой блок кода.
{: .language-markdown}

Вот результат такой разметки:

Какой-то код.

Это тот же блок кода.
А это уже другой блок кода.

Код также можно оборачивать тильдами (~)— по три или больше с каждого края. Это так называемый синтаксис “огороженных блоков”, язык при такой разметке указывается сразу после верхней “ограды”

   ~~~~~~~~markdown
   Код, опять код.
   ~~~~~~~~
   ~~~~~~~~markdown
   Код, опять код.
   ~~~~~~~~

В Jekyll при активации опции input: GFM код можно выделять по стандарту Github тройными обратными апострофами с указанием языка и этот способ является предпочтительным.

   ```markdown
         ( \
       \ \
       / /                |\\
      / /     .-`````-.   / ^`-.
      \ \    /         \_/  {|} `o
       \ \  /   .---.   \\ _  ,--'
        \ \/   /     \,  \( `^^^
         \   \/\      (\  )
          \   ) \     ) \ \
      jgs  ) /__ \__  ) (\ \___
          (___)))__))(__))(__)))
   ```
      ( \
       \ \
       / /                |\\
      / /     .-`````-.   / ^`-.
      \ \    /         \_/  {|} `o
       \ \  /   .---.   \\ _  ,--'
        \ \/   /     \,  \( `^^^
         \   \/\      (\  )
          \   ) \     ) \ \
      jgs  ) /__ \__  ) (\ \___
          (___)))__))(__))(__)))

Блок кода оборачивается тегами <pre> и <code> одновременно. При задании языка к ним добавляется класс “language-указанный-язык”.

Подсветка кода

Подсветка кода осуществляется в kramdown автоматически при указании языка кода. Для настройки подсветки существуют следующие опции:

Название опции Настройка
syntax_highlighter установка системы подсветки кода, по умолчанию в kramdown это coderay
syntax_highlighter_opts настройка системы подсветки кода, опции передаются в виде пар ключ/значение и должны быть понятны системе подсветки

Для дефолтной системы подсветки coderay есть специальные опции:

Название опции Настройка
coderay_bold_every определяет, какие строки в нумерации должны быть выделены жирным шрифтом, по умолчанию задано значение 10 (каждая десятая строка), для отключения надо задать false.
coderay_css способ задания подсветки: классами CSS (class) или инлайновыми стилями (style — это значение по умолчанию).
coderay_default_lang язык, синтаксис которого подсвечивается при отсутствии указания языка в блоке кода. По умолчанию nil.
coderay_line_number_start стартовый номер для нумерации строк кода, по умолчанию 1.
coderay_line_numbers механизм вывода номеров строк: табличный (table) или строчный (inline — дефолтный). Значение nil отключает нумерацию.
coderay_tab_width ширина табуляции в подсвечиваемом коде.
coderay_wrap блок-обертка для кода — span, div или nil. Значение по умолчанию div.

Система подсветки кода coderay генерирует классы для блоков кода, несовместимые с Pygments и подобными системами (Rouge, Prism).

Типографские символы

В kramdown поддерживается расширение SmartyPants, улучшающее типографику.

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

русское название английское название до после
длинное тире m-dash ---
короткое тире n-dash --
многоточие ellipsis ...
французские кавычки guillemets << >> « »
двойные кавычки * curly double quotes "" "X" ”” “X”
одинарные кавычки * curly single quotes '' 'X' ’’ ‘X’

Для конвертации кавычек есть специальная опция — smart_quotes. Ее дефолтное значение lsquo,rsquo,ldquo,rdquo— по порядку: левая одинарная, правая одинарная, левая двойная и правая двойная кавычки. С полным списком доступных вариантов кавычек можно ознакомиться в википедии.

Многоточие, в принципе, можно и убрать из списка — оно по умолчанию трансформируется из трех подряд поставленных точек в большинстве браузеров. Все остальное выглядит прекрасно, но как известно, основная проблема всех средств для улучшения типографики это то, что ими мало кто пользуется. Хотя с учетом распространенности SmartyPants имеет смысл постоянно использовать в разметке длинное тире при пунктуации и короткое тире при указании диапазонов.

Горизонтальные линии

Сколько угодно! Для генерации hr достаточно трех или более астерисков, дефисов или подчеркиваний, их можно разделять пробелами или табами, но нельзя смешивать на одной линии.

* * *   **  **

---

    _  _  _  _

---------------

Экранирование

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

Это  \`не код\`, а просто текст в обратных апострофах.

Это `не код`, а просто текст в обратных апострофах

Список экранируемых символов:
Символ английское именование русское именование
\ backslash обратный слэш
. period точка
* asterisk астериск
_ underscore подчеркивание
+ plus плюс
- minus минус
= equal sign равно
` back tick обратный апостроф
()[]{}<> left and right parens/brackets/braces/angle brackets левая и правая скобки/ квадратные/ фигурные/ угловые
# hash хэш
! bang восклицательный знак
« left guillemet меньше
» right guillemet больше
: colon двоеточие
| pipe вертикальная черта
double quote двойная кавычка
single quote одинарная кавычка
$ dollar sign знак доллара

Примечание: внутри таблиц вертикальная черта (|) после экранирования не выводится совсем. Ее надо обернуть тегом code.