Использование Maruku (часть №1)

В этом посте я собираюсь начать цикл статей, рассказывающих о Maruku.

Maruku это движок, который позволяет конвертировать текст в XHTML представление этого текста на основе специализированного “легковесного” языка разметки под названием Markdown.

Пару замечаний по абзацу выше:

• Maruku использует в своей работе Markdown, но не просто использует, а ещё и расширяет его возможности. Как он это делает, я расскажу ниже.

• Помимо преобразования в XHTML существует ещё возможность преобразования в LaTeX и PDF (предварительно преобразовав его в LaTeX). В планах у разработчиков добавление возможности конвертирования в сам Markdown (без специфических особенностей присутствующих в расширении этого языка от Maruku) и Textile2. Ценность последних конверторов, на мой взгляд, довольно сомнительная.

О самом Markdown я не вижу сейчас смысла рассказывать т.к. в интернете полно документации. Вот лишь несколько ссылок:

• Markdown в Wikipedia(ru) и Wikipedia(en)
• Описание синтаксиса Markdown от Daring Fireball
• Загляните в каталог <путь к каталогу с gem-ами>/gems/maruku-0.5.9/docs, а затем в файл markdown_syntax.html

Поэтому расскажу как Maruku расширяет Markdown. Начну я с того, что расскажу о двух основных категориях элементов разметки:

• span-элемент - это такой элемент разметки, который состоит из одной строки текста (т.е. в нем нет переходов на новую строку). Как правило, эти элементы конвертируются в строковые (или как их ещё называют встроенные) элементы HTML. Например, _такой текст на Markdown_ будет преобразован в <em>такой текст на Markdown</em>

• блочный элемент - такой элемент может состоять из нескольких строк. Примером такого элемента в Markdown может являться таблица или параграф

А теперь поговорим о расширениях. Их существует два вида:

Inline Attribute Lists (IAL)

В данном случае рядом с элементом разметки появляется конструкция вида:

{: <список атрибутов> }

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

Это пример расширения _span-элемента_{: style="color:red" }

А это пример 
расширения блочного
элемента
{: style="background-color:silver" }

А вот результат:

Это пример расширения span-элемента

А это пример расширения блочного элемента

Как вы заметили, в качестве списка атрибутов применяются атрибуты допустимые для HTML элементов. Но допустимы и следующие сокращения:

.<имя CSS класса> - будет преобразовано в class=”<имя CSS класса>”. Соответственно если такие конструкции встречаются несколько раз то все они будут помешены внутрь одного элемента class, как того требует спецификация CSS

#<id элемента> - будет преобразовано в id=”<id элемента>”.

key=value - будет преобразовано в атрибут key=value. Если value содержит пробелы, то его надо заключить в двойные кавычки.

ref_id - т.е. просто идентификатор без префиксов (# или .) говорит о том, что к элементу будет применяться стиль, описанный в ALD расширении. Без этой возможности Maruku не особо бы отличался от RedCloth. Но об этом ниже.

Attribute Lists Definitions (ALD)

А вот здесь начинаются чудеса :)

Вы можете объявить в любом месте вашей разметки конструкцию вида:

{:<ref_id>: <список атрибутов> }

а затем ссылаться на это объявление в любом IAL используя указанный вами ref_id

Пример:

Текст
{: red }

{:red: style="background-color: silver" }

Текст
{: red }

А вот результат:

Текст

Текст

На этом пока всё. В следующий раз я расскажу вам как подключить и использовать Maruku в своём приложении.