From 62d3312b7ad09fe8cca1488b3e09e8be86c79fdd Mon Sep 17 00:00:00 2001 From: Tony Brix Date: Mon, 1 May 2023 23:30:06 -0500 Subject: [PATCH] fix: deprecate options (#2766) BREAKING CHANGE: deprecate options --- docs/USING_ADVANCED.md | 73 ++++++++++++++-------------------------- src/helpers.js | 36 ++++++++++++++++++-- src/marked.js | 4 +-- test/unit/marked-spec.js | 7 ++-- 4 files changed, 65 insertions(+), 55 deletions(-) diff --git a/docs/USING_ADVANCED.md b/docs/USING_ADVANCED.md index e6a96d01..969c0b97 100644 --- a/docs/USING_ADVANCED.md +++ b/docs/USING_ADVANCED.md @@ -2,14 +2,13 @@ ```js import { marked } from 'marked'; -marked.parse(markdownString [,options] [,callback]) +marked.parse(markdownString [,options]) ``` -|Argument |Type |Notes | -|:---------------------|:------------|:----------------------------------------------------------------------------------------------------| -|markdownString |`string` |String of markdown source to be compiled. | -|options|`object`|Hash of options. Can also use `marked.setOptions`. | -|callback |`function` |Called when `markdownString` has been parsed. Can be used as second argument if no `options` present.| +|Argument |Type |Notes | +|:-----------------------------|:-------|:---------------------------------------------------------------| +|markdownString |`string`|String of markdown source to be compiled. | +|options|`object`|Hash of options. Can also use `marked.use` to set global options| ### Alternative using reference @@ -18,21 +17,10 @@ marked.parse(markdownString [,options] [,callback]) import { marked } from 'marked'; // Set options -// `highlight` example uses https://highlightjs.org -marked.setOptions({ - renderer: new marked.Renderer(), - highlight: function(code, lang) { - const hljs = require('highlight.js'); - const language = hljs.getLanguage(lang) ? lang : 'plaintext'; - return hljs.highlight(code, { language }).value; - }, - langPrefix: 'hljs language-', // highlight.js css expects a top-level 'hljs' class. +marked.use({ + async: true, pedantic: false, gfm: true, - breaks: false, - sanitize: false, - smartypants: false, - xhtml: false }); // Compile @@ -44,23 +32,23 @@ console.log(marked.parse(markdownString)); |Member |Type |Default |Since |Notes | |:-----------|:---------|:--------|:--------|:-------------| |async |`boolean` |`false` |4.1.0 |If true, `walkTokens` functions can be async and `marked.parse` will return a promise that resolves when all walk tokens functions resolve.| -|baseUrl |`string` |`null` |0.3.9 |A prefix url for any relative link. | |breaks |`boolean` |`false` |v0.2.7 |If true, add `
` on a single line break (copies GitHub behavior on comments, but not on rendered markdown files). 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).| -|headerPrefix|`string` |`''` |v0.3.0 |A string to prefix the `id` attribute when emitting headings (h1, h2, h3, etc).| -|highlight |`function`|`null` |v0.3.0 |A function to highlight code blocks, see Asynchronous highlighting.| -|langPrefix |`string` |`'language-'`|v0.3.0|A string to prefix the className in a `` 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) for more details.| -|sanitize |`boolean` |`false` |v0.2.1 |If true, sanitize the HTML passed into `markdownString` with the `sanitizer` function.
**Warning**: This feature is deprecated and it should NOT be used as it cannot be considered secure.
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.| -|smartypants |`boolean` |`false` |v0.2.9 |If true, use "smart" typographic punctuation for things like quotes and dashes.| +|silent |`boolean` |`false` |v0.2.7 |If true, the parser does not throw any exception or log any warning. Any error will be returned as a string.| |tokenizer |`object` |`new Tokenizer()`|v1.0.0|An object containing functions to create tokens from markdown. See [extensibility](/using_pro) for more details.| |walkTokens |`function` |`null`|v1.1.0|A function which is called for every token. See [extensibility](/using_pro) for more details.| -|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.| +|baseUrl (**deprecated**)|`string` |`null` |v0.3.9 |Deprecated in v5.0.0 use [`marked-base-url`](https://www.npmjs.com/package/marked-base-url) to prefix url for any relative link. | +|headerIds (**deprecated**)|`boolean` |`true` |v0.4.0 |Deprecated in v5.0.0 use [`marked-gfm-heading-id`](https://www.npmjs.com/package/marked-gfm-heading-id) to include an `id` attribute when emitting headings (h1, h2, h3, etc).| +|headerPrefix (**deprecated**)|`string` |`''` |v0.3.0 |Deprecated in v5.0.0 use [`marked-gfm-heading-id`](https://www.npmjs.com/package/marked-gfm-heading-id) to add a string to prefix the `id` attribute when emitting headings (h1, h2, h3, etc).| +|highlight (**deprecated**)|`function`|`null` |v0.3.0 |Deprecated in v5.0.0 use [`marked-highlight`](https://www.npmjs.com/package/marked-highlight) to add highlighting to code blocks. | +|langPrefix (**deprecated**)|`string` |`'language-'`|v0.3.0|Deprecated in v5.0.0 use [`marked-highlight`](https://www.npmjs.com/package/marked-highlight) to prefix the className in a `` block. Useful for syntax highlighting.| +|mangle (**deprecated**)|`boolean` |`true` |v0.3.4 |Deprecated in v5.0.0 use [`marked-mangle`](https://www.npmjs.com/package/marked-mangle) to mangle email addresses.| +|sanitize (**deprecated**)|`boolean` |`false` |v0.2.1 |If true, sanitize the HTML passed into `markdownString` with the `sanitizer` function.
**Warning**: This feature is deprecated and it should NOT be used as it cannot be considered secure.
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 (**deprecated**)|`function`|`null` |v0.3.4 |A function to sanitize the HTML passed into `markdownString`.| +|smartypants (**deprecated**)|`boolean` |`false` |v0.2.9 |Deprecated in v5.0.0 use [`marked-smartypants`](https://www.npmjs.com/package/marked-smartypants) to use "smart" typographic punctuation for things like quotes and dashes.| +|xhtml (**deprecated**)|`boolean` |`false` |v0.3.2 |Deprecated in v5.0.0 use [`marked-xhtml`](https://www.npmjs.com/package/marked-xhtml) to emit self-closing HTML tags for void elements (<br/>, <img/>, etc.) with a "/" as required by XHTML.|

Known Extensions

@@ -71,14 +59,19 @@ Marked can be extended using [custom extensions](/using_pro#extensions). This is |Name|Package Name|Description| |:---|:-----------|:----------| |[Admonition](https://www.npmjs.com/package/marked-admonition-extension)|[`marked-admonition-extension`](https://www.npmjs.com/package/marked-admonition-extension)| Admonition extension | +|[Base URL](https://github.com/markedjs/marked-base-url)|[`marked-base-url`](https://www.npmjs.com/package/marked-base-url)|Prefix relative urls with a base URL.| |[Bidi](https://github.com/markedjs/marked-bidi)|[`marked-bidi`](https://www.npmjs.com/package/marked-bidi)|Add Bidirectional text support to the HTML| |[Custom Heading ID](https://github.com/markedjs/marked-custom-heading-id)|[`marked-custom-heading-id`](https://www.npmjs.com/package/marked-custom-heading-id)|Specify a custom heading id in headings with the [Markdown Extended Syntax](https://www.markdownguide.org/extended-syntax/#heading-ids) `# heading {#custom-id}`| |[Emoji](https://github.com/UziTech/marked-emoji)|[`marked-emoji`](https://www.npmjs.com/package/marked-emoji)|Add emoji support like on GitHub| |[Extended Tables](https://github.com/calculuschild/marked-extended-tables)|[`marked-extended-tables`](https://www.npmjs.com/package/marked-extended-tables)|Extends the standard Github-Flavored tables to support advanced features: Column Spanning, Row Spanning, Multi-row headers| |[GFM Heading ID](https://github.com/markedjs/marked-gfm-heading-id)|[`marked-gfm-heading-id`](https://www.npmjs.com/package/marked-gfm-heading-id)|Use [`github-slugger`](https://github.com/Flet/github-slugger) to create the heading IDs and allow a custom prefix.| +|[Highlight](https://github.com/markedjs/marked-highlight)|[`marked-highlight`](https://www.npmjs.com/package/marked-highlight)|Highlight code blocks| |[Katex Code](https://github.com/UziTech/marked-katex-extension)|[`marked-katex-extension`](https://www.npmjs.com/package/marked-katex-extension)|Render [katex](https://katex.org/) code| |[LinkifyIt](https://github.com/UziTech/marked-linkify-it)|[`marked-linkify-it`](https://www.npmjs.com/package/marked-linkify-it)|Use [linkify-it](https://github.com/markdown-it/linkify-it) for urls| +|[Mangle](https://github.com/markedjs/marked-mangle)|[`marked-mangle`](https://www.npmjs.com/package/marked-mangle)|Mangle mailto links with HTML character references| |[Misskey-flavored Markdown](https://akkoma.dev/sfr/marked-mfm)|[`marked-mfm`](https://www.npmjs.com/package/marked-mfm)|Custom extension for [Misskey-flavored Markdown](https://github.com/misskey-dev/mfm.js/blob/develop/docs/syntax.md).| +|[Smartypants](https://github.com/markedjs/marked-smartypants)|[`marked-smartypants`](https://www.npmjs.com/package/marked-smartypants)|Use [smartypants](https://www.npmjs.com/package/smartypants) to use "smart" typographic punctuation for things like quotes and dashes.| +|[XHTML](https://github.com/markedjs/marked-xhtml)|[`marked-xhtml`](https://www.npmjs.com/package/marked-xhtml)|Emit self-closing HTML tags for void elements (<br/>, <img/>, etc.) with a "/" as required by XHTML.|

Inline Markdown

@@ -92,25 +85,9 @@ const inlineHtml = marked.parseInline('**strong** _em_'); console.log(inlineHtml); // 'strong em' ``` -

Asynchronous highlighting

+

Highlighting

-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 -marked.setOptions({ - highlight: function(code, lang, callback) { - require('pygmentize-bundled') ({ lang: lang, format: 'html' }, code, function (err, result) { - callback(err, result.toString()); - }); - } -}); - -marked.parse(markdownString, (err, html) => { - console.log(html); -}); -``` - -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. +Use [`marked-highlight`](https://www.npmjs.com/package/marked-highlight) to highlight code blocks.

Workers

diff --git a/src/helpers.js b/src/helpers.js index df7b0bb2..e9eddd77 100644 --- a/src/helpers.js +++ b/src/helpers.js @@ -232,10 +232,42 @@ export function findClosingBracket(str, b) { return -1; } -export function checkSanitizeDeprecation(opt) { - if (opt && opt.sanitize && !opt.silent) { +export function checkDeprecations(opt, callback) { + if (!opt || opt.silent) { + return; + } + + if (callback) { + console.warn('marked(): callback is deprecated since version 5.0.0, should not be used and will be removed in the future. Read more here: https://marked.js.org/using_pro#async'); + } + + if (opt.sanitize || opt.sanitizer) { console.warn('marked(): sanitize and sanitizer parameters are deprecated since version 0.7.0, should not be used and will be removed in the future. Read more here: https://marked.js.org/#/USING_ADVANCED.md#options'); } + + if (opt.highlight || opt.langPrefix) { + console.warn('marked(): highlight and langPrefix parameters are deprecated since version 5.0.0, should not be used and will be removed in the future. Instead use https://www.npmjs.com/package/marked-highlight.'); + } + + if (opt.mangle) { + console.warn('marked(): mangle parameter is deprecated since version 5.0.0, should not be used and will be removed in the future. Instead use https://www.npmjs.com/package/marked-mangle.'); + } + + if (opt.baseUrl) { + console.warn('marked(): baseUrl parameter is deprecated since version 5.0.0, should not be used and will be removed in the future. Instead use https://www.npmjs.com/package/marked-base-url.'); + } + + if (opt.smartypants) { + console.warn('marked(): smartypants parameter is deprecated since version 5.0.0, should not be used and will be removed in the future. Instead use https://www.npmjs.com/package/marked-smartypants.'); + } + + if (opt.xhtml) { + console.warn('marked(): xhtml parameter is deprecated since version 5.0.0, should not be used and will be removed in the future. Instead use https://www.npmjs.com/package/marked-xhtml.'); + } + + if (opt.headerIds || opt.headerPrefix) { + console.warn('marked(): headerIds and headerPrefix parameters are deprecated since version 5.0.0, should not be used and will be removed in the future. Instead use https://www.npmjs.com/package/marked-gfm-heading-id.'); + } } // copied from https://stackoverflow.com/a/5450113/806777 diff --git a/src/marked.js b/src/marked.js index 36ec0403..b721d665 100644 --- a/src/marked.js +++ b/src/marked.js @@ -6,7 +6,7 @@ import { TextRenderer } from './TextRenderer.js'; import { Slugger } from './Slugger.js'; import { Hooks } from './Hooks.js'; import { - checkSanitizeDeprecation, + checkDeprecations, escape } from './helpers.js'; import { @@ -64,7 +64,7 @@ function parseMarkdown(lexer, parser) { + Object.prototype.toString.call(src) + ', string expected')); } - checkSanitizeDeprecation(opt); + checkDeprecations(opt, callback); if (opt.hooks) { opt.hooks.options = opt; diff --git a/test/unit/marked-spec.js b/test/unit/marked-spec.js index a4cb681d..fb02954f 100644 --- a/test/unit/marked-spec.js +++ b/test/unit/marked-spec.js @@ -766,6 +766,7 @@ used extension2 walked

walked++; } }; + use({ silent: true }); use(extension); marked('text', () => { expect(walked).toBe(2); @@ -897,6 +898,7 @@ paragraph describe('async highlight', () => { let highlight, markdown; beforeEach(() => { + marked.use({ silent: true }); highlight = jasmine.createSpy('highlight', (text, lang, callback) => { setImmediate(() => { callback(null, `async ${text || ''}`); @@ -948,10 +950,9 @@ text 1 let numErrors = 0; marked(markdown, { highlight }, (err, html) => { - expect(err).toBeTruthy(); - expect(html).toBeUndefined(); + expect(html).toContain('An error occurred:'); - if (err) { + if (err || html.includes('An error occurred:')) { numErrors++; }