fix: deprecate options (#2766)

BREAKING CHANGE: deprecate options
markedjs · May 2, 2023 · 62d3312 · zyxd · May 2, 2023 · 62d3312
1 parent c6852f5
commit 62d3312
Show file tree

Hide file tree

Showing 4 changed files with 65 additions and 55 deletions.
diff --git 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.                                                            |
-|<a href="#options">options</a>|`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.                       |
+|<a href="#options">options</a>|`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 `<br>` 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 <a href="#highlight">Asynchronous highlighting</a>.|
-|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) 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.|
-|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 (&lt;br/&gt;, &lt;img/&gt;, 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 `<code>` 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.<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  (**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 (&lt;br/&gt;, &lt;img/&gt;, etc.) with a "/" as required by XHTML.|
 
 <h2 id="extensions">Known Extensions</h2>
 
@@ -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 (&lt;br/&gt;, &lt;img/&gt;, etc.) with a "/" as required by XHTML.|
 
 <h2 id="inline">Inline Markdown</h2>
 
@@ -92,25 +85,9 @@ const inlineHtml = marked.parseInline('**strong** _em_');
 console.log(inlineHtml); // '<strong>strong</strong> <em>em</em>'
 ```
 
-<h2 id="highlight">Asynchronous highlighting</h2>
+<h2 id="highlight">Highlighting</h2>
 
-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.
 
 <h2 id="workers">Workers</h2>
 

diff --git 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
@@ -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
@@ -766,6 +766,7 @@ used extension2 walked</p>
         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++;
       }