Markdown

24 April 2011 #markdown #design

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

Собственно, Markdown — это простой текст.

Когда я переходил на jekyll одной из причин было именно использование языка разметки Markdown.

Jekyll использует markdown нативно, вообще данный язык разметки очень любят на GitHub, используют его везде, где только можно (и в комментариях, и в отчетах, и в readme файлах). Почему спросите вы, очень просто, работать с ним куда удобнее, чем использовать нативный html или любой из редакторов.

Синтаксис

Оригинальное описание синтаксиса находится здесь (англ.): http://daringfireball.net/projects/markdown/syntax

Русский перевод официальной документации можно найти здесь: http://markdown.pp.ru/

Ниже следует краткое описание синтаксиса.

  • Абзацы разделяются пустой строкой
  • Два или более пробела на конце строки задают разрыв строки
  • Шрифты: **жирный**, _курсив_, `моноширинный`
  • Заголовки:
    • Atx-style: #первый уровень#, ##второй уровень## и т.д.
    • Setext-style: подчеркивание знаками = задает первый уровень, дефисами - — второй
  • Цитаты: > текст цитаты
  • Списки:
    • неупорядоченные: * элемент списка (также могут использоваться символы - или +).
    • упорядоченные: 1. элемент списка
  • Блок кода — каждая строка начинается с 4 или более пробелов
  • Горизонтальная черта: три или более дефиса или звездочки
  • Ссылки:
    • встроенные [label](url)
    • автоматические <url>
    • в виде сносок
  • Изображения:
    • встроенные ![alt text](url)
    • в виде сносок
  • Экранирование символов — чтобы вставить спецсимвол, используемый в разметке, как обычный символ, его нужно предварить символом обратной косой черты. Экранироваться должны следующие символы: * _ { } [ ] ( ) # + - . !

Использование

В Jekyll есть возможность использовать следующие движки Markdown:

По умолчанию, если не указывается иное, используется движок Maruku. Однако при первых же тестах показало свою несостоятельность. Генерация сайта занимала очень много времени, при этом было очень много сообщений об ошибках и предупреждениях. Практически сразу же я стал использовать Rdiscount. Время генерации всего сайта стало занимать всего несколько секунд, и при этом никаких ошибок.

Я бы продолжил использовать данный генератор, если бы не одно НО. Выяснилось, что Rdiscount не умеет обрабатывать дополнительные параметры тегов. То есть нет возможности указывать классы, идентификаторы. Что, естественно, несколько ограничивает использование стилей на сайте. Как оказалось, данную возможность имеет движок Maruku, но его использовать я не хотел в виду тех проблем, что осветил выше. Решил искать альтернативу.

Странно, что раньше я упускал из виду генератор Kramdown. Фактически я его игнорировал, не замечал. И только на днях “вспомнил” о нем и попробовал использовать. Время генерации примерно то же, что и у Rdiscount, но есть возможность использования параметров в тегах. Делается это примерно следующим образом:

> A nice blockquote
{: .class1 .class2}

На выходе получаем следующий html-код:

<blockquote class="class1 class2">
  <p>A nice blockquote</p>
</blockquote>

То есть все, что необходимо для работы в данном генераторе присутствует.

Установка

Для использования генераторов Markdown на машине необходимо установить ruby и gem:

$ sudo aptitude install ruby-full rubygems

И теперь можно устанавливать сами генераторы:

$ sudo gem install kramdown

Теперь создаем обычный текстовый файл, прописываем текст. После чего для генерации html-файла используется команда:

$ kramdown file.markdown > file.html

При использовании Jekyll достаточно в файле _config.yml прописать строку с указанием используемого генератора:

markdown:    kramdown

Итоги

С того момента, как я стал использовать Markdown я ощутил всю прелесть работы с “нормальными” редакторами, а не убожеством, типа веб-редактора Wordpress. Появляется желание писать и писать, работать, не останавливаясь. При этом текст воспринимается и читается именно как обычный текст, ничто не мешает его восприятию и, соответственно, работы с ним.

Никак не могу понять, почему markdown до сих пор не используется так широко, как мог бы?

Для примера выкладываю код данной страницы в формате markdown на странице gist.gihub.com