@4qwerty7/syzoj-renderer 中文文档教程
syzoj-renderer
SYZOJ 的 markdown、math 和 highlight 渲染器。
Example
let { markdown, highlight } = require('syzoj-renderer');
console.log(await markdown(text));
console.log(await highlight(code, language));
API
async markdown(text, [cache, filterFunction, options])
text
是要渲染的 Markdown 文本。
cache
是 null
或具有两个函数的对象来操作键值存储(key
在传递到 cache):
async get(string key)
async set(string key, string value)
filterFunction(html)
是一个过滤呈现的 HTML 的函数。 它可以用来防止 XSS 攻击。 应该返回过滤后的 HTML。
options
是一个对象,可能包含:
markdownIt
: Overrides default options innew MarkdownIt(options)
. (See markdown-it)markdownItMath
: Overrides default options inmarkdownIt.use(MathdownItMath, options)
. (See markdown-it-math-loose)markdownItMergeCells
: Set to false to disable markdown-it-merge-cells in markdown tables, which will merge adjacent cells with same content in tableshighlight
: Same ashighlight
'soptions
parameter, used when highlighting code in markdown.
返回呈现的 HTML。 不会扔。
async highlight(code, language[, cache, options])
用 pygments 高亮一些代码。
code
是要高亮显示的代码。 language
是code
的语言。
cache
与markdown()
中的参数相同。
options
是一个对象,可能包含:
pygments
: Overrides default options inPygments.pygmentize(code, options)
. (See pygments-promise)highlighter
: Pass a functionasync function (code, language)
to replace the defualt pygments highlighter. If a function is passed, pygments won't be used andpygments
option will be ignored.wrapper
: An array[before, after]
. Highlighted code's HTML will be wrapped bybefore
andafter
. Defaults to['<pre>
.', '
</pre>']
返回 HTML 中突出显示的代码。 不会扔。
Notes
- Markdown backend is markdown-it.
- GFM is supported.
- By default,
linkify
andhtml
are enabled,typographer
andbreaks
are disabled.
- By default, code highlight's backend is pygments, which requires pygments to be installed.
- If no
pygmentize
is available, it'll always return unhighlighted code. pygmentize
's default commandline arguments are:pygmentize -l <language> -f html -P nowrap=false -P classprefix=pl-
.- A theme CSS is required to display highlighted code properly. See Generating styles section of pygments's document.
- If no
- Math backend is mathjax-node-page.
- Maths are rendered to
<svg>
HTML elements,dist/math.css
is required to display properly. - Maths with spaces within dollar sign like
$ a+b $
will work. - Complex maths like
$ \sum\limits_{i=0}^na_i $
won't be broken by Markdown. - To ensure each document's math rendering state isolated,
\require
is disabled. - Maths that failed to render would result in displaying error message.
- Maths are rendered to
License
AGPL-3.0。 如果您真的希望这是 MIT 许可证,请与我联系。
syzoj-renderer
SYZOJ's renderer for markdown, math and highlight.
Example
let { markdown, highlight } = require('syzoj-renderer');
console.log(await markdown(text));
console.log(await highlight(code, language));
API
async markdown(text, [cache, filterFunction, options])
text
is the Markdown text to be rendered.
cache
is null
or a object with two functions to manipulate a Key-Value store (key
is hashed before passing to cache
):
async get(string key)
async set(string key, string value)
filterFunction(html)
is a function to filter rendered HTML. It can be used to prevent XSS attack. Should return filtered HTML.
options
is a object, may contain:
markdownIt
: Overrides default options innew MarkdownIt(options)
. (See markdown-it)markdownItMath
: Overrides default options inmarkdownIt.use(MathdownItMath, options)
. (See markdown-it-math-loose)markdownItMergeCells
: Set to false to disable markdown-it-merge-cells in markdown tables, which will merge adjacent cells with same content in tableshighlight
: Same ashighlight
'soptions
parameter, used when highlighting code in markdown.
Return rendered HTML. Won't throw.
async highlight(code, language[, cache, options])
Highlight some code with pygments.
code
is the code to be highlighted. language
is code
's language.
cache
is same as the parameter in markdown()
.
options
is a object, may contain:
pygments
: Overrides default options inPygments.pygmentize(code, options)
. (See pygments-promise)highlighter
: Pass a functionasync function (code, language)
to replace the defualt pygments highlighter. If a function is passed, pygments won't be used andpygments
option will be ignored.wrapper
: An array[before, after]
. Highlighted code's HTML will be wrapped bybefore
andafter
. Defaults to['<pre>
.', '
</pre>']
Return highlighted code in HTML. Won't throw.
Notes
- Markdown backend is markdown-it.
- GFM is supported.
- By default,
linkify
andhtml
are enabled,typographer
andbreaks
are disabled.
- By default, code highlight's backend is pygments, which requires pygments to be installed.
- If no
pygmentize
is available, it'll always return unhighlighted code. pygmentize
's default commandline arguments are:pygmentize -l <language> -f html -P nowrap=false -P classprefix=pl-
.- A theme CSS is required to display highlighted code properly. See Generating styles section of pygments's document.
- If no
- Math backend is mathjax-node-page.
- Maths are rendered to
<svg>
HTML elements,dist/math.css
is required to display properly. - Maths with spaces within dollar sign like
$ a+b $
will work. - Complex maths like
$ \sum\limits_{i=0}^na_i $
won't be broken by Markdown. - To ensure each document's math rendering state isolated,
\require
is disabled. - Maths that failed to render would result in displaying error message.
- Maths are rendered to
License
AGPL-3.0. Contact me if you really want this to be MIT license.