Javascript-parser NPM

Парсер для 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="файл для смайла">
кавычки "..." - на ёлочки «...»