Parser for the extended markdown format used at javascript.ru
npm install javascript-parser
Парсер для адаптированного формата Markdown, который используется на Javascript.ru.
У него есть два режима работы:
1. Доверенный -- для статей, задач и другого основного материала. Возможны любые теги и т.п.
2. Безопасный -- для комментариев и другого user-generated content. Большинство тегов HTML можно использовать.
jsБлок кода вставляется как в github:
`js`
alert(1);
Или:
`html`
<!DOCTYPE HTML>
<title>Viva la HTML5!</title>
Поддерживаемые языки (список может быть расширен):
- html
- js
- css
- coffee
- php
- http
- java
- ruby
- scss
- sql
Если хочется, чтобы посетитель мог запустить код -- добавьте первую строку //+ run:
`js`
//+ run
alert(1);
Независимо от языка можно использовать любой стиль комментария: //+ ... , /+ ... /, #+ ... или ,
главное чтобы он был первой строкой и в начале был плюс и пробел. Этот комментарий не попадёт в итоговый вывод.
Есть два языка, для которых это поддерживается:
1. js - в доверенном режиме через eval, в безопасном -- в iframe с другого домена.html
2. - в доверенном режиме показ будет в iframe с того же домена, в безопасном -- с другого домена.
Прочие настройки, возможные в этой же строке:
- height=100 -- высота (в пикселях) для iframe, в котором будет выполняться пример. Обычно для HTML она вычисляется автоматически по содержимому.src="my.js"
- -- код будет взят из файла my.js autorun
- -- пример будет запущен автоматически по загрузке страницы.refresh
- -- каждый запуск JS-кода будет осуществлён в "чистом" окружении. iframe
Этот флаг актуален только для безопасного режима, т.к. обычно с другого домена кешируется и используется многократно.demo
- - флаг актуален только для решений задач, он означает, что при нажатии на кнопку "Демо" в условии запустится этот код.
Пример ниже возьмёт код из файла my.js и запускает его автоматически:`js`
//+ src="my.js" autorun
Этот пример будет при запуске показан в
Поддерживаются два выделения:
Блочное выделение -- несколько строк выделяются полностью.
Обозначается строками ! в начале и /! в конце:`js`
!
function important() {
alert("Важный блок");
}
/!
Также можно выделить отдельную строку (одну), поставив в конце !:
`js`
function important() {
alert("Важная строка");!
}
Инлайн-выделение выделяет фрагмент текста, например важное слово, для этого оно заключается в !.../!:`css`
!h1/! {
background: pink !important/!;
}
В примере выше выделятся h1 и important.
$3
Для вставки кода в строку он оборачивается в обратные кавычки `...`.
Например:
Функция _.partialделает то же, что иbind, но без привязки контекстаthis.
Весь HTML внутри таких кавычек автоматически экранируется и оборачивается в :
Теги `<script>` и `<b>`
-- станет
Теги <code><script></code> и <code><b></code>
Обычно это удобно, но если экранирование не нужно -- можно использовать HTML-тег ... напрямую:
Функция <code>reduce<em>Right</em></code>
После открывающей и перед закрывающей обратными кавычками ` не должно быть пробелов, такой текст не будет отформатирован:
От ` до `
Это позволяет избежать неверных интерпретаций в тексте.
Если нужно вставить именно саму обратную кавычку, а она воспринимается как код - используйте Unicode-entity: `.
Во-первых, заметим, что любой js/html-код можно сделать запускаемым, добавив в начало //+ run.
При этом HTML будет при запуске показываться в
ББ-теги, описанные ниже, дают альтернативные способы показа примера.
Для того, чтобы они работали, пример должен быть в отдельной директории без поддиректорий, выложенной как plunk при помощи утилиты https://github.com/iliakan/plunk.
Кроме того, в примере должен быть файл index.html.
ББ-тег [iframe] позволяет показать пример в действии в
Покажет пример cool-stuff/index.html, без кода. height=100
Параметры:
- -- высота (если автовычисленная не подходит)link
- -- добавить в ифрейм ссылку для открытия в новом окнеplay
- -- добавить в ифрейм ссылку для открытия в песочницеzip
- -- добавить в ифрейм ссылку на скачивание архива с примером[iframe src="..."]
Обычно чистый используется для показа "как работает" пример без возможности залезть в код, например в качестве демки для задачи.
Если пример содержит несколько важных файлов -- его можно показать через [example].
Это то же самое, что [iframe], но дополнительно над
Например:
[example src="cool-stuff"]
Для показа списка достоинств/недостатков:
[compare]
+ WebSocket'ы дают минимальную задержку в передаче данных
+ WebSocket'ы позволяют непрерывно передавать данные в обе стороны
- Не поддерживаются в IE<10
[/compare]
У достоинств в начале должен стоять плюс +, у недостатков минус -, строки без ± недопустимы.
Ссылки можно задавать вместо Википедия вот так:
Википедия
Для показа ссылки без особого заголовка:
[http://wikipedia.org]()
-- станет
<a href="http://wikipedia.org">http://wikipedia.org</a>
Для ссылки на статью или задачу с сайта можно использовать только её абсолютный URL, заголовок подставится автоматически, например:
Читайте об этом в главе [](/events)
-- станет (из базы будет получен заголовок)
Читайте об этом в главе <a href="/events">События</a>
Для того, чтобы сослаться на заголовок, у которого есть [#anchor]:
Оператор instanceof
-- станет (если есть статья с заголовокм [#instanceof])
<a href="/url-этой-статьи#instanceof">Оператор <code>instanceof</code></a>
,[pre]
Не применяется форматирование в HTML-комментариях и тегах:
-