hexo-renderer-marked


Add support for [Markdown]. This plugin uses [marked] as its render engine.

Important note on security

By default, this plugin contains a potential security issue: It is possible to inject Markdown containing Unsafe HTML that will not be sanitized

This issue might not affect you because you checked the content of the markdown before using this plugin, but it's still a risk

There are two solutions to avoid those issues:

1. First solution is to enable option dompurify: true, which will sanitize the rendered HTML. The side effect of this solution is that it will break any tag plugin (aka {% codeblock %}). This explains why the safer option has not been enabled by default
2. Second solution is to migrate to hexo-renderer-markdown-it which is safe by default and does not suffer from the same limitations

Installation

``bash
$ npm install hexo-renderer-marked --save
`

- Hexo 4: >= 2.0
- Hexo 3: >= 0.2
- Hexo 2: 0.1.x

Options

You can configure this plugin in _config.yml.

`yml
marked:
gfm: true
pedantic: false
breaks: true
smartLists: true
smartypants: true
quotes: '“”‘’'
modifyAnchors: 0
anchorAlias: false
autolink: true
mangle: true
sanitizeUrl: false
dompurify: false
headerIds: true
lazyload: false
figcaption: false
prependRoot: true
postAsset: false
external_link:
enable: false
exclude: []
nofollow: false
disableNunjucks: false
descriptionLists: true
`

- gfm - Enables GitHub flavored markdown
- pedantic - Conform to obscure parts of markdown.pl as much as possible. Don't fix any of the original markdown bugs or poor behavior.
- breaks - Enable GFM line breaks. This option requires the gfm option to be true.
- smartLists - Use smarter list behavior than the original markdown.
- smartypants - Use "smart" typographic punctuation for things like quotes and dashes.
- quotes - Defines the double and single quotes used for substituting regular quotes if smartypants is enabled.
* Example: '«»“”'
* "double" will be turned into «double»
* 'single' will be turned into “single”
* Both double and single quotes substitution must be specified, otherwise it will be silently ignored.
- modifyAnchors - Transform the anchorIds into lower case (1) or upper case (2).
- autolink - Enable autolink for URLs. E.g. https://hexo.io will become https://hexo.io.
- mangle - Escape autolinked email address with HTML character references.
* This is to obscure email address from _basic_ crawler used by spam bot, while still readable to web browsers.
- sanitizeUrl - Remove URLs that start with javascript:, vbscript: and data:.
- dompurify - Enable DOMPurify to be run on the rendered Markdown. See below for configuration
- headerIds - Insert header id, e.g.

text

. Useful for inserting anchor link to each paragraph with a heading.
- anchorAlias - Enables custom header id
* Example: ## foo, id will be set as "bar".
* Requires headerIds to be enabled.
- lazyload - Lazy loading images via loading="lazy" attribute.
- figcaption - Append figcaption element after each image.
- prependRoot - Prepend root value to (internal) image path.
* Example _config.yml:
`yml
root: /blog/
`
* !text becomes
- postAsset - Resolve post asset's image path to relative path and prepend root value when post_asset_folder is enabled.
* "image.jpg" is located at "/2020/01/02/foo/image.jpg", which is a post asset of "/2020/01/02/foo/".
*  becomes
* Requires prependRoot to be enabled.
- external_link
* enable - Open external links in a new tab.
* exclude - Exclude hostname. Specify subdomain when applicable, including www.
- Example: foo becomes foo
* nofollow - Add rel="noopener external nofollow noreferrer" to all external links for security, privacy and SEO. Read more. _This can be enabled regardless of external_link.enable_
- Example: foo becomes foo
- disableNunjucks: If true, Nunjucks tags {{ }} or {% %} (usually used by tag plugins) will not be rendered.
- descriptionLists: Enable support for description lists syntax.
* Currently description lists syntax is not in neither CommonMark or GFM, hexo-renderer-marked only provides the option for backward compatibility.
* By disabling the descriptionLists, markdown rendering performance will be improved by a lot.

For more options, see Marked. Due to the customizations implemented by this plugin, some of the Marked's options may not work as expected. Feel free to raise an issue to us for clarification.

Extras

$3

DOMPurify can be enabled to sanitize the rendered HTML.

To enable it, pass an object containing the DOMPurify options:

`yml
dompurify: true
`

Or you can enable specific DOMPurify options (but according to DOMPurify authors, the default options are safe):

`yml
dompurify:
FORBID_TAGS:
- "style"
`

See https://github.com/cure53/DOMPurify#can-i-configure-dompurify for a full reference of available options

$3

hexo-renderer-marked also implements description/definition lists using the same syntax as [PHP Markdown Extra][PHP Markdown Extra].

This Markdown:

`markdown
Definition Term
: This is the definition for the term
`

will generate this HTML:

`html


Definition Term

This is the definition for the term


`

Note: There is currently a limitation in this implementation. If multiple definitions are provided, the rendered HTML will be incorrect.

For example, this Markdown:

`markdown
Definition Term
: Definition 1
: Definition 2
`

will generate this HTML:

`html


Definition Term
: Definition 1

Definition 2


`

If you've got ideas on how to support multiple definitions, please provide a pull request. We'd love to support it.

$3

This plugin overrides some default behaviours of how [marked] plugin renders the markdown into html, to integrate with the Hexo ecosystem. It is possible to override this plugin too, without resorting to forking the whole thing.

For example, to override how heading like # heading text is rendered:

`js
hexo.extend.filter.register('marked:renderer', function(renderer) {
const { config } = this; // Optional if you don't need user config from _config.yml
renderer.heading = function({ tokens, depth: level }) {
const text = this.parser.parseInline(tokens);
// Default behaviour
// return ${text};
// outputs

heading text

// If you want to insert custom class name
return ${text};
// outputs

heading text


}
})
`

Save the file in "scripts/" folder and run Hexo as usual.

Refer to renderer.js on how this plugin overrides the default methods. For other methods not covered by this plugin, refer to marked's documentation.

#### Tokenizer

It is also possible to customize the tokenizer.

`js
const { escapeHTML: escape } = require('hexo-util');

// https://github.com/markedjs/marked/blob/b6773fca412c339e0cedd56b63f9fa1583cfd372/src/Lexer.js#L8-L24
// Replace dashes only
const smartypants = (str) => {
return str
// em-dashes
.replace(/---/g, '\u2014')
// en-dashes
.replace(/--/g, '\u2013')
};

hexo.extend.filter.register('marked:tokenizer', function(tokenizer) {
const { smartypants: isSmarty } = this.config.marked;
tokenizer.inlineText = function(src, inRawBlock) {
const { rules } = this;

// https://github.com/markedjs/marked/blob/b6773fca412c339e0cedd56b63f9fa1583cfd372/src/Tokenizer.js#L643-L658
const cap = rules.inline.text.exec(src);
if (cap) {
let text;
if (inRawBlock) {
text = cap[0];
} else {
text = escape(isSmarty ? smartypants(cap[0]) : cap[0]);
}
return {
// type value is a corresponding renderer method
// https://marked.js.org/using_pro#inline-level-renderer-methods
type: 'text',
raw: cap[0],
text
};
}
}
});
`

#### Extensions

It is also possible to customize the extensions.
For example, use KaTeX to render block-level math:

`js
const katex = require('katex');

hexo.extend.filter.register('marked:extensions', function(extensions) {
// Info: extensions is an array.
extensions.push({
name: 'blockMath',
level: 'block',
tokenizer(src) {
const cap = /^\s{0,3}\$\$((?:[^\n]|\n[^\n])+?)\n{0,1}\$\$/.exec(src);

if (cap !== null) {
return {
type: 'blockMath',
raw: cap[0],
math: cap[1]
};
}

return undefined;
},
renderer(token) {
return

${katex.renderToString(token.math, {displayMode: true})}

\n;
}
});
});
`

You may also get access to marked.use function.
For example to use the marked-alert extention wich also provides a walkTokens functions:

`js
const markedAlert = require('marked-alert');

hexo.extend.filter.register('marked:use', function (markedUse) {
markedUse(markedAlert());
});
``

[Markdown]: https://daringfireball.net/projects/markdown/
[marked]: https://github.com/chjj/marked
[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/#def-list