@4qwerty7/syzoj-renderer 中文文档教程

发布于 3年前 浏览 19 项目主页 更新于 3年前

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 文本。

cachenull 或具有两个函数的对象来操作键值存储(key 在传递到 cache):

  • async get(string key)
  • async set(string key, string value)

filterFunction(html) 是一个过滤呈现的 HTML 的函数。 它可以用来防止 XSS 攻击。 应该返回过滤后的 HTML。

options 是一个对象,可能包含:

  • markdownIt: Overrides default options in new MarkdownIt(options). (See markdown-it)
  • markdownItMath: Overrides default options in markdownIt.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 tables
  • highlight: Same as highlight's options parameter, used when highlighting code in markdown.

返回呈现的 HTML。 不会扔。

async highlight(code, language[, cache, options])

用 pygments 高亮一些代码。

code是要高亮显示的代码。 languagecode 的语言。

cachemarkdown() 中的参数相同。

options 是一个对象,可能包含:

  • pygments: Overrides default options in Pygments.pygmentize(code, options). (See pygments-promise)
  • highlighter: Pass a function async function (code, language) to replace the defualt pygments highlighter. If a function is passed, pygments won't be used and pygments option will be ignored.
  • wrapper: An array [before, after]. Highlighted code's HTML will be wrapped by before and after. Defaults to ['<pre>', '</pre>'].

返回 HTML 中突出显示的代码。 不会扔。

Notes

  • Markdown backend is markdown-it.
    • GFM is supported.
    • By default, linkify and html are enabled, typographer and breaks 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.
  • 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.

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 in new MarkdownIt(options). (See markdown-it)
  • markdownItMath: Overrides default options in markdownIt.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 tables
  • highlight: Same as highlight's options 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 in Pygments.pygmentize(code, options). (See pygments-promise)
  • highlighter: Pass a function async function (code, language) to replace the defualt pygments highlighter. If a function is passed, pygments won't be used and pygments option will be ignored.
  • wrapper: An array [before, after]. Highlighted code's HTML will be wrapped by before and after. Defaults to ['<pre>', '</pre>'].

Return highlighted code in HTML. Won't throw.

Notes

  • Markdown backend is markdown-it.
    • GFM is supported.
    • By default, linkify and html are enabled, typographer and breaks 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.
  • 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.

License

AGPL-3.0. Contact me if you really want this to be MIT license.

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文