Парсер для JavaScript.ru

Парсер для адаптированного формата Markdown, который используется на Javascript.ru.

У него есть два режима работы:

1. Доверенный -- для статей, задач и другого основного материала. Возможны любые теги и т.п.
2. Безопасный -- для комментариев и другого user-generated content. Большинство тегов HTML можно использовать.

Вставка кода ```js

Блок кода вставляется как в github:

Или:

Поддерживаемые языки (список может быть расширен):

• html
• js
• css
• coffee
• php
• http
• java
• ruby
• scss
• sql

Выполняемый код //+ run и другие настройки

Если хочется, чтобы посетитель мог запустить код -- добавьте первую строку //+ run:

Независимо от языка можно использовать любой стиль комментария: //+ ... , /*+ ... */, #+ ... или <!--+ ... -->, главное чтобы он был первой строкой и в начале был плюс и пробел. Этот комментарий не попадёт в итоговый вывод.

Есть два языка, для которых это поддерживается:

1. js - в доверенном режиме через eval, в безопасном -- в iframe с другого домена.
2. html - в доверенном режиме показ будет в iframe с того же домена, в безопасном -- с другого домена.

Прочие настройки, возможные в этой же строке:

• height=100 -- высота (в пикселях) для iframe, в котором будет выполняться пример. Обычно для HTML она вычисляется автоматически по содержимому.
• src="my.js" -- код будет взят из файла my.js
• autorun -- пример будет запущен автоматически по загрузке страницы.
• refresh -- каждый запуск JS-кода будет осуществлён в "чистом" окружении. Этот флаг актуален только для безопасного режима, т.к. обычно iframe с другого домена кешируется и используется многократно.
• demo - флаг актуален только для решений задач, он означает, что при нажатии на кнопку "Демо" в условии запустится этот код.

Пример ниже возьмёт код из файла my.js и запускает его автоматически:

Этот пример будет при запуске показан в <iframe> высотой 100px:

Выделение в блоке кода *!*

Поддерживаются два выделения:

Блочное выделение -- несколько строк выделяются полностью.

Обозначается строками *!* в начале и */!* в конце:

Также можно выделить отдельную строку (одну), поставив в конце *!*:

Инлайн-выделение выделяет фрагмент текста, например важное слово, для этого оно заключается в *!*...*/!*:

В примере выше выделятся h1 и important.

Код в строке `...`

Для вставки кода в строку он оборачивается в обратные кавычки `...`.

Например:

Весь HTML внутри таких кавычек автоматически экранируется и оборачивается в <code>:

Обычно это удобно, но если экранирование не нужно -- можно использовать HTML-тег <code>...</code> напрямую:

После открывающей и перед закрывающей обратными кавычками ` не должно быть пробелов, такой текст не будет отформатирован:

Это позволяет избежать неверных интерпретаций в тексте. Если нужно вставить именно саму обратную кавычку, а она воспринимается как код - используйте Unicode-entity: `.

Показ примеров в <iframe>

Во-первых, заметим, что любой js/html-код можно сделать запускаемым, добавив в начало //+ run.

При этом HTML будет при запуске показываться в <iframe> снизу. Можно даже добавить autorun для автозапуска при загрузке страницы.

ББ-теги, описанные ниже, дают альтернативные способы показа примера.

Для того, чтобы они работали, пример должен быть в отдельной директории без поддиректорий, выложенной как plunk при помощи утилиты https://github.com/iliakan/plunk. Кроме того, в примере должен быть файл index.html.

[iframe] для показа примера в <iframe>

ББ-тег [iframe] позволяет показать пример в действии в <iframe>'е с минимальными "декорациями".

Например:

Покажет пример cool-stuff/index.html, без кода.

Параметры:

• height=100 -- высота (если автовычисленная не подходит)
• link -- добавить в ифрейм ссылку для открытия в новом окне
• play -- добавить в ифрейм ссылку для открытия в песочнице
• zip -- добавить в ифрейм ссылку на скачивание архива с примером

Обычно чистый [iframe src="..."] используется для показа "как работает" пример без возможности залезть в код, например в качестве демки для задачи.

[example] для показа файлов в табах

Если пример содержит несколько важных файлов -- его можно показать через [example].

Это то же самое, что [iframe], но дополнительно над <iframe>'ом будет лента с табами файлов примера. Любой файл можно выбрать и посмотреть.

Например:

Сравнение [compare]

Для показа списка достоинств/недостатков:

У достоинств в начале должен стоять плюс +, у недостатков минус -, строки без ± недопустимы.

Ссылки [...]()

Ссылки можно задавать вместо <a href="http://wikipedia.org">Википедия</a> вот так:

Для показа ссылки без особого заголовка:

Для ссылки на статью или задачу с сайта можно использовать только её абсолютный URL, заголовок подставится автоматически, например:

Для того, чтобы сослаться на заголовок, у которого есть [#anchor]:

Отмена форматирования <pre>, [pre]

Не применяется форматирование в HTML-комментариях <!-- ... --> и тегах:

• <script> <style> <object> <embed> <video> <audio> <pre>

Также форматирование не будет применяться, если обернуть секцию в [pre]...[/pre]:

Заголовки #Header и якоря [#anchor]

Заголовки начинаются с символа решётки #, сколько решёток -- такой и уровень.

На любой заголовок можно сделать общесайтовую ссылку, добавив к нему [#anchor], где anchor -- имя для <a name="...">, в который заголовок обёрнут.

Это имя также запоминается в базе и далее в любой другой статье или задаче можно просто использовать ссылку [читайте тут](#anchor) для отправки посетителя сразу на нужный заголовок.

Жирный **, курсив *, перечёркивание ~

Как в обычном Markdown:

Выделение в середине слова не работает.

• Перед открывающим символом должен быть пробел, а после -- нет.
• После закрывающего символа должен быть побел или пунктуация, а перед -- нет пробела

Например:

Типографика

Автоматически заменяются:

• (c) (r) (tm) (p) +- -> <- на символы © ® ℗ ± → ←
• троеточие ... на один юникодный символ-троеточие …
• одиночный дефис - на юникодный символ-аналог –, двойной дефис -- на длинное тире —
• смайлы :) :( и ряд других - на картинки <img src="файл для смайла">
• кавычки "..." - на ёлочки «...»

Двойной (или более) перевод строки означает параграф <p>.

Не ставятся <p> между блочными тегами, например в таком тексте параграфа между <div> и <table> не будет:

Сочетания клавиш [key]

Для красивого отображения сочетаний клавиш используется бб-тег [key Ctrl+Shift+P].

Библиотеки [libs]

Если нужны одна или несколько библиотек -- перечислите их построчно в секции [libs].

Например:

Все они попадут в <head>, CSS будут до скриптов.

Можно перечислить не полные скрипты, а мнемо-имена, сейчас поддерживается только d3:

Скрипты и стили [head]

Скрипты и стили, которые хочется отправить в <head>, можно обернуть в [head]:

Неподдерживаемый Markdown

• Списки (используйте <ul>, <ol> и <dl>).
• Таблицы (используйте <table>).
• Код при помощи отступов.
• Подчёркивание (лучше не использовать, достаточно * и **).
• Ряд других возможностей, используемых редко и имеющих HTML-аналоги.