diff options
Diffstat (limited to 'packages/markdown/marked/docs/USING_ADVANCED.md')
| -rw-r--r-- | packages/markdown/marked/docs/USING_ADVANCED.md | 102 |
1 files changed, 88 insertions, 14 deletions
diff --git a/packages/markdown/marked/docs/USING_ADVANCED.md b/packages/markdown/marked/docs/USING_ADVANCED.md index 6490caa7..81df205b 100644 --- a/packages/markdown/marked/docs/USING_ADVANCED.md +++ b/packages/markdown/marked/docs/USING_ADVANCED.md @@ -14,18 +14,19 @@ marked(markdownString [,options] [,callback]) ```js // Create reference instance -var myMarked = require('marked'); +const marked = require('marked'); // Set options // `highlight` example uses `highlight.js` -myMarked.setOptions({ - renderer: new myMarked.Renderer(), - highlight: function(code) { - return require('highlight.js').highlightAuto(code).value; +marked.setOptions({ + renderer: new marked.Renderer(), + highlight: function(code, language) { + const hljs = require('highlight.js'); + const validLanguage = hljs.getLanguage(language) ? language : 'plaintext'; + return hljs.highlight(validLanguage, code).value; }, pedantic: false, gfm: true, - tables: true, breaks: false, sanitize: false, smartLists: true, @@ -34,14 +35,14 @@ myMarked.setOptions({ }); // Compile -console.log(myMarked('I am using __markdown__.')); +console.log(marked(markdownString)); ``` <h2 id="options">Options</h2> |Member |Type |Default |Since |Notes | |:-----------|:---------|:--------|:--------|:-------------| -|baseUrl |`string` |`null` |0.3.9 |A prefix url for any relative link. | +|baseUrl |`string` |`null` |0.3.9 |A prefix url for any relative link. | |breaks |`boolean` |`false` |v0.2.7 |If true, add `<br>` on a single line break (copies GitHub). Requires `gfm` be `true`.| |gfm |`boolean` |`true` |v0.2.1 |If true, use approved [GitHub Flavored Markdown (GFM) specification](https://github.github.com/gfm/).| |headerIds |`boolean` |`true` |v0.4.0 |If true, include an `id` attribute when emitting headings (h1, h2, h3, etc).| @@ -50,13 +51,12 @@ console.log(myMarked('I am using __markdown__.')); |langPrefix |`string` |`'language-'`|v0.3.0|A string to prefix the className in a `<code>` block. Useful for syntax highlighting.| |mangle |`boolean` |`true` |v0.3.4 |If true, autolinked email address is escaped with HTML character references.| |pedantic |`boolean` |`false` |v0.2.1 |If true, conform to the original `markdown.pl` as much as possible. Don't fix original markdown bugs or behavior. Turns off and overrides `gfm`.| -|renderer |`object` |`new Renderer()`|v0.3.0|An object containing functions to render tokens to HTML. See [extensibility](USING_PRO.md) for more details.| -|sanitize |`boolean` |`false` |v0.2.1 |If true, sanitize the HTML passed into `markdownString` with the `sanitizer` function.| +|renderer |`object` |`new Renderer()`|v0.3.0|An object containing functions to render tokens to HTML. See [extensibility](/#/USING_PRO.md) for more details.| +|sanitize |`boolean` |`false` |v0.2.1 |If true, sanitize the HTML passed into `markdownString` with the `sanitizer` function.<br>**Warning**: This feature is deprecated and it should NOT be used as it cannot be considered secure.<br>Instead use a sanitize library, like [DOMPurify](https://github.com/cure53/DOMPurify) (recommended), [sanitize-html](https://github.com/apostrophecms/sanitize-html) or [insane](https://github.com/bevacqua/insane) on the output HTML! | |sanitizer |`function`|`null` |v0.3.4 |A function to sanitize the HTML passed into `markdownString`.| |silent |`boolean` |`false` |v0.2.7 |If true, the parser does not throw any exception.| |smartLists |`boolean` |`false` |v0.2.8 |If true, use smarter list behavior than those found in `markdown.pl`.| |smartypants |`boolean` |`false` |v0.2.9 |If true, use "smart" typographic punctuation for things like quotes and dashes.| -|tables |`boolean` |`true` |v0.2.7 |If true and `gfm` is true, use [GFM Tables extension](https://github.github.com/gfm/#tables-extension-).| |xhtml |`boolean` |`false` |v0.3.2 |If true, emit self-closing HTML tags for void elements (<br/>, <img/>, etc.) with a "/" as required by XHTML.| <h2 id="highlight">Asynchronous highlighting</h2> @@ -64,7 +64,7 @@ console.log(myMarked('I am using __markdown__.')); Unlike `highlight.js` the `pygmentize.js` library uses asynchronous highlighting. This example demonstrates that marked is agnostic when it comes to the highlighter you use. ```js -myMarked.setOptions({ +marked.setOptions({ highlight: function(code, lang, callback) { require('pygmentize-bundled') ({ lang: lang, format: 'html' }, code, function (err, result) { callback(err, result.toString()); @@ -72,7 +72,81 @@ myMarked.setOptions({ } }); -console.log(myMarked(markdownString)); +console.log(marked(markdownString)); ``` -In both examples, `code` is a `string` representing the section of code to pass to the highlighter. In this example, `lang` is a `string` informing the highlighter what programming lnaguage to use for the `code` and `callback` is the `function` the asynchronous highlighter will call once complete. +In both examples, `code` is a `string` representing the section of code to pass to the highlighter. In this example, `lang` is a `string` informing the highlighter what programming language to use for the `code` and `callback` is the `function` the asynchronous highlighter will call once complete. + +<h2 id="workers">Workers</h2> + +To prevent ReDoS attacks you can run marked on a worker and terminate it when parsing takes longer than usual. + +Marked can be run in a [worker thread](https://nodejs.org/api/worker_threads.html) on a node server, or a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) in a browser. + +### Node Worker Thread + +```js +// markedWorker.js + +const marked = require('marked'); +const { parentPort } = require('worker_threads'); + +parentPort.on('message', (markdownString) => { + parentPort.postMessage(marked(markdownString)); +}); +``` + +```js +// index.js + +const { Worker } = require('worker_threads'); +const markedWorker = new Worker('./markedWorker.js'); + +const markedTimeout = setTimeout(() => { + markedWorker.terminate(); + throw new Error('Marked took too long!'); +}, timeoutLimit); + +markedWorker.on('message', (html) => { + clearTimeout(markedTimeout); + console.log(html); + markedWorker.terminate(); +}); + +markedWorker.postMessage(markdownString); +``` + +### Web Worker + +> **NOTE**: Web Workers send the payload from `postMessage` in an object with the payload in a `.data` property + +```js +// markedWorker.js + +importScripts('path/to/marked.min.js'); + +onmessage = (e) => { + const markdownString = e.data + postMessage(marked(markdownString)); +}; +``` + +```js +// script.js + +const markedWorker = new Worker('./markedWorker.js'); + +const markedTimeout = setTimeout(() => { + markedWorker.terminate(); + throw new Error('Marked took too long!'); +}, timeoutLimit); + +markedWorker.onmessage = (e) => { + clearTimeout(markedTimeout); + const html = e.data; + console.log(html); + markedWorker.terminate(); +}; + +markedWorker.postMessage(markdownString); +``` |