remark-parse - npm Package Compare versions

Comparing version 10.0.2 to 11.0.0

index.d.ts

@@ -1,9 +0,55 @@
-// This wrapper exists because JS in TS can’t export a `@type` of a function.
 import type {Root} from 'mdast'
+import type {Extension as FromMarkdownExtension} from 'mdast-util-from-markdown'
+import type {Extension as MicromarkExtension} from 'micromark-util-types'
 import type {Plugin} from 'unified'
 import type {Options} from './lib/index.js'
 
-declare const remarkParse: Plugin<[(Options | undefined)?], string, Root>
+export type {Options} from './lib/index.js'
+
+/**
+ * Add support for parsing from markdown.
+ *
+ * @this
+ *   Unified processor.
+ * @param
+ *   Configuration (optional).
+ * @returns
+ *   Nothing.
+ */
+declare const remarkParse: Plugin<
+  [(Readonly<Options> | null | undefined)?],
+  string,
+  Root
+>
 export default remarkParse
 
-export type {Options} from './lib/index.js'
+// Add custom settings supported when `remark-parse` is added.
+declare module 'unified' {
+  interface Settings extends Options {}
+
+  interface Data {
+    /**
+     * List of `micromark` extensions to use.
+     *
+     * This type is registered by `remark-parse`.
+     * Values can be registered by remark plugins that extend `micromark` and
+     * `mdast-util-from-markdown`.
+     * See {@link MicromarkExtension | `Extension`} from
+     * {@link https://github.com/micromark/micromark/tree/main/packages/micromark-util-types | `micromark-util-types`}.
+     */
+    micromarkExtensions?: MicromarkExtension[]
+
+    /**
+     * List of `mdast-util-from-markdown` extensions to use.
+     *
+     * This type is registered by `remark-parse`.
+     * Values can be registered by remark plugins that extend `micromark` and
+     * `mdast-util-from-markdown`.
+     * See {@link FromMarkdownExtension | `Extension`} from
+     * {@link https://github.com/syntax-tree/mdast-util-from-markdown#extension | `mdast-util-from-markdown`}.
+     */
+    fromMarkdownExtensions?: Array<
+      FromMarkdownExtension[] | FromMarkdownExtension
+    >
+  }
+}

index.js

@@ -0,1 +1,2 @@
+// Note: types exposed from `index.d.ts`.
 export {default} from './lib/index.js'

lib/index.d.ts

@@ -1,11 +0,26 @@
-export default function remarkParse(
-  this: import('unified').Processor<
-    import('mdast').Root,
-    import('mdast').Root,
-    void,
-    void
-  >,
-  ...settings: [import('mdast-util-from-markdown').Options?] | void[]
-): void
-export type Root = import('mdast').Root
-export type Options = import('mdast-util-from-markdown').Options
+/**
+ * Aadd support for parsing from markdown.
+ *
+ * @param {Readonly<Options> | null | undefined} [options]
+ *   Configuration (optional).
+ * @returns {undefined}
+ *   Nothing.
+ */
+export default function remarkParse(options?: Readonly<Options> | null | undefined): undefined;
+export default class remarkParse {
+    /**
+     * Aadd support for parsing from markdown.
+     *
+     * @param {Readonly<Options> | null | undefined} [options]
+     *   Configuration (optional).
+     * @returns {undefined}
+     *   Nothing.
+     */
+    constructor(options?: Readonly<Options> | null | undefined);
+    parser: (document: string, file: import("vfile").VFile) => import("mdast").Root;
+}
+export type Root = import('mdast').Root;
+export type FromMarkdownOptions = import('mdast-util-from-markdown').Options;
+export type Parser = import('unified').Parser<Root>;
+export type Processor = import('unified').Processor<Root>;
+export type Options = Omit<FromMarkdownOptions, 'extensions' | 'mdastExtensions'>;

lib/index.js

 /**
  * @typedef {import('mdast').Root} Root
- * @typedef {import('mdast-util-from-markdown').Options} Options
+ * @typedef {import('mdast-util-from-markdown').Options} FromMarkdownOptions
+ * @typedef {import('unified').Parser<Root>} Parser
+ * @typedef {import('unified').Processor<Root>} Processor
  */
 
+/**
+ * @typedef {Omit<FromMarkdownOptions, 'extensions' | 'mdastExtensions'>} Options
+ */
+
 import {fromMarkdown} from 'mdast-util-from-markdown'
 
 /**
- * @this {import('unified').Processor}
- * @type {import('unified').Plugin<[Options?] | void[], string, Root>}
+ * Aadd support for parsing from markdown.
+ *
+ * @param {Readonly<Options> | null | undefined} [options]
+ *   Configuration (optional).
+ * @returns {undefined}
+ *   Nothing.
  */
 export default function remarkParse(options) {
-  /** @type {import('unified').ParserFunction<Root>} */
-  const parser = (doc) => {
-    // Assume options.
-    const settings = /** @type {Options} */ (this.data('settings'))
+  /** @type {Processor} */
+  // @ts-expect-error: TS in JSDoc generates wrong types if `this` is typed regularly.
+  const self = this
 
-    return fromMarkdown(
-      doc,
-      Object.assign({}, settings, options, {
-        // Note: these options are not in the readme.
-        // The goal is for them to be set by plugins on `data` instead of being
-        // passed by users.
-        extensions: this.data('micromarkExtensions') || [],
-        mdastExtensions: this.data('fromMarkdownExtensions') || []
-      })
-    )
+  self.parser = parser
+
+  /**
+   * @type {Parser}
+   */
+  function parser(doc) {
+    return fromMarkdown(doc, {
+      ...self.data('settings'),
+      ...options,
+      // Note: these options are not in the readme.
+      // The goal is for them to be set by plugins on `data` instead of being
+      // passed by users.
+      extensions: self.data('micromarkExtensions') || [],
+      mdastExtensions: self.data('fromMarkdownExtensions') || []
+    })
   }
-
-  Object.assign(this, {Parser: parser})
 }

package.json

 {
   "name": "remark-parse",
-  "version": "10.0.2",
+  "version": "11.0.0",
   "description": "remark plugin to add support for parsing markdown input",
   "license": "MIT",
   "keywords": [
-    "unified",
+    "abstract",
+    "ast",
+    "markdown",
+    "mdast",
+    "parse",
+    "plugin",
     "remark",
     "remark-plugin",
-    "plugin",
-    "markdown",
-    "mdast",
-    "abstract",
     "syntax",
     "tree",
-    "ast",
-    "parse"
+    "unified"
   ],
@@ -36,4 +36,3 @@ "homepage": "https://remark.js.org",
   "type": "module",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "exports": "./index.js",
   "files": [
@@ -45,16 +44,31 @@ "lib/",
   "dependencies": {
-    "@types/mdast": "^3.0.0",
-    "mdast-util-from-markdown": "^1.0.0",
-    "unified": "^10.0.0"
+    "@types/mdast": "^4.0.0",
+    "mdast-util-from-markdown": "^2.0.0",
+    "micromark-util-types": "^2.0.0",
+    "unified": "^11.0.0"
   },
-  "scripts": {
-    "test": "node --conditions development test.js"
-  },
-  "xo": false,
+  "scripts": {},
   "typeCoverage": {
     "atLeast": 100,
     "detail": true,
-    "strict": true,
-    "ignoreCatch": true
+    "ignoreCatch": true,
+    "strict": true
+  },
+  "xo": {
+    "overrides": [
+      {
+        "files": [
+          "**/*.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/ban-types": "off",
+          "@typescript-eslint/consistent-type-definitions": "off"
+        }
+      }
+    ],
+    "prettier": true,
+    "rules": {
+      "unicorn/no-this-assignment": "off"
+    }
   }
 }

readme.md

@@ -11,3 +11,3 @@ # remark-parse
 
-**[remark][]** plugin to add support for parsing markdown input.
+**[remark][]** plugin to add support for parsing from markdown.
 
@@ -39,21 +39,18 @@ ## Contents
 
-This plugin is built on [`mdast-util-from-markdown`][mdast-util-from-markdown],
-which in turn uses [`micromark`][micromark] for parsing markdown into tokens and
-turns those into [mdast][] syntax trees.
-remark focusses on making it easier to transform content by abstracting such
-internals away.
+See [the monorepo readme][remark] for info on what the remark ecosystem is.
 
-**unified** is a project that transforms content with abstract syntax trees
-(ASTs).
-**remark** adds support for markdown to unified.
-**mdast** is the markdown AST that remark uses.
-**micromark** is the markdown parser we use.
-This is a remark plugin that defines how input markdown is turned into mdast.
-
 ## When should I use this?
 
 This plugin adds support to unified for parsing markdown.
-You can alternatively use [`remark`][remark-core] instead, which combines
-unified, this plugin, and [`remark-stringify`][remark-stringify].
+If you also need to serialize markdown, you can alternatively use
+[`remark`][remark-core], which combines unified, this plugin, and
+[`remark-stringify`][remark-stringify].
 
+If you *just* want to turn markdown into HTML (with maybe a few extensions),
+we recommend [`micromark`][micromark] instead.
+If you don’t use plugins and want to access the syntax tree, you can directly
+use [`mdast-util-from-markdown`][mdast-util-from-markdown].
+remark focusses on making it easier to transform content by abstracting these
+internals away.
+
 You can combine this plugin with other plugins to add syntax extensions.
@@ -66,13 +63,8 @@ Notable examples that deeply integrate with it are
 [`remark-directive`][remark-directive].
-You can also use any other [remark plugin][plugin] after `remark-parse`.
+You can also use any other [remark plugin][remark-plugin] after `remark-parse`.
 
-If you *just* want to turn markdown into HTML (with maybe a few extensions),
-we recommend [`micromark`][micromark] instead.
-If you want to handle syntax trees manually, you can use
-[`mdast-util-from-markdown`][mdast-util-from-markdown].
-
 ## Install
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+This package is [ESM only][esm].
+In Node.js (version 16+), install with [npm][]:
 
@@ -86,3 +78,3 @@ ```sh
 ```js
-import remarkParse from 'https://esm.sh/remark-parse@10'
+import remarkParse from 'https://esm.sh/remark-parse@11'
 ```
@@ -94,3 +86,3 @@
 <script type="module">
-  import remarkParse from 'https://esm.sh/remark-parse@10?bundle'
+  import remarkParse from 'https://esm.sh/remark-parse@11?bundle'
 </script>
@@ -104,27 +96,31 @@ ```
 ```js
-import {unified} from 'unified'
+import rehypeStringify from 'rehype-stringify'
+import remarkGfm from 'remark-gfm'
 import remarkParse from 'remark-parse'
-import remarkGfm from 'remark-gfm'
 import remarkRehype from 'remark-rehype'
-import rehypeStringify from 'rehype-stringify'
+import {unified} from 'unified'
 
-main()
+const doc = `
+# Mercury
 
-async function main() {
-  const file = await unified()
-    .use(remarkParse)
-    .use(remarkGfm)
-    .use(remarkRehype)
-    .use(rehypeStringify)
-    .process('# Hi\n\n*Hello*, world!')
+**Mercury** is the first planet from the [Sun](https://en.wikipedia.org/wiki/Sun)
+and the smallest planet in the Solar System.
+`
 
-  console.log(String(file))
-}
+const file = await unified()
+  .use(remarkParse)
+  .use(remarkGfm)
+  .use(remarkRehype)
+  .use(rehypeStringify)
+  .process(doc)
+
+console.log(String(file))
 ```
 
-Running that with `node example.js` yields:
+…then running `node example.js` yields:
 
 ```html
-<h1>Hi</h1>
-<p><em>Hello</em>, world!</p>
+<h1>Mercury</h1>
+<p><strong>Mercury</strong> is the first planet from the <a href="https://en.wikipedia.org/wiki/Sun">Sun</a>
+and the smallest planet in the Solar System.</p>
 ```
@@ -135,9 +131,16 @@
 This package exports no identifiers.
-The default export is `remarkParse`.
+The default export is [`remarkParse`][api-remark-parse].
 
 ### `unified().use(remarkParse)`
 
-Add support for parsing markdown input.
-There are no options.
+Add support for parsing from markdown.
 
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Nothing (`undefined`).
+
 ## Examples
@@ -149,26 +152,30 @@
 Non-standard markdown extensions can be enabled with plugins.
-The following example adds support for GFM features (autolink literals,
+
+This example shows how to support GFM features (autolink literals,
 footnotes, strikethrough, tables, tasklists) and frontmatter (YAML):
 
 ```js
-import {unified} from 'unified'
-import remarkParse from 'remark-parse'
+import rehypeStringify from 'rehype-stringify'
 import remarkFrontmatter from 'remark-frontmatter'
 import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
 import remarkRehype from 'remark-rehype'
-import rehypeStringify from 'rehype-stringify'
+import {unified} from 'unified'
 
-main()
+const doc = `---
+layout: solar-system
+---
 
-async function main() {
-  const file = await unified()
-    .use(remarkParse)
-    .use(remarkFrontmatter)
-    .use(remarkGfm)
-    .use(remarkRehype)
-    .use(rehypeStringify)
-    .process('---\nlayout: home\n---\n\n# Hi ~~Mars~~Venus!')
+# Hi ~~Mars~~Venus!
+`
 
-  console.log(String(file))
-}
+const file = await unified()
+  .use(remarkParse)
+  .use(remarkFrontmatter)
+  .use(remarkGfm)
+  .use(remarkRehype)
+  .use(rehypeStringify)
+  .process(doc)
+
+console.log(String(file))
 ```
@@ -187,21 +194,22 @@
 They use an old markup format called roff.
-There’s a remark plugin, [`remark-man`][remark-man], that can serialize as roff.
-The following example turns markdown into man pages by using unified with
+There’s a remark plugin, [`remark-man`][remark-man], that can serialize as
+roff.
+
+This example shows how to turn markdown into man pages by using unified with
 `remark-parse` and `remark-man`:
 
 ```js
+import remarkMan from 'remark-man'
+import remarkParse from 'remark-parse'
 import {unified} from 'unified'
-import remarkParse from 'remark-parse'
-import remarkMan from 'remark-man'
 
-main()
+const doc = `
+# titan(7) -- largest moon of saturn
 
-async function main() {
-  const file = await unified()
-    .use(remarkParse)
-    .use(remarkMan)
-    .process('# titan(7) -- largest moon of saturn\n\nTitan is the largest moon…')
+Titan is the largest moon…
+`
 
-  console.log(String(file))
-}
+const file = await unified().use(remarkParse).use(remarkMan).process(doc)
+
+console.log(String(file))
 ```
@@ -212,3 +220,3 @@
 ```roff
-.TH "TITAN" "7" "November 2021" "" ""
+.TH "TITAN" "7" "September 2023" "" ""
 .SH "NAME"
@@ -229,3 +237,3 @@ \fBtitan\fR - largest moon of saturn
 
-The syntax tree format used in remark is [mdast][].
+The syntax tree used in remark is [mdast][].
 
@@ -235,11 +243,14 @@ ## Types
 This package is fully typed with [TypeScript][].
-There are no extra exported types.
+It exports the additional type `Options` (which is currently empty).
 
 ## Compatibility
 
-Projects maintained by the unified collective are compatible with all maintained
+Projects maintained by the unified collective are compatible with maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
-Our projects sometimes work with older versions, but this is not guaranteed.
 
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line, `remark-parse@^11`,
+compatible with Node.js 16.
+
 ## Security
@@ -249,4 +260,4 @@
 [cross-site scripting (XSS)][xss] attacks, use of remark can be unsafe.
-When going to HTML, you will likely combine remark with **[rehype][]**, in which
-case you should use [`rehype-sanitize`][rehype-sanitize].
+When going to HTML, you will combine remark with **[rehype][]**, in which case
+you should use [`rehype-sanitize`][rehype-sanitize].
 
@@ -273,4 +284,2 @@ Use of remark plugins could also open you up to other attacks.
 
-<!--lint ignore no-html-->
-
 <table>
@@ -324,2 +333,6 @@ <tr valign="middle">
 <td width="10%" align="center">
+  <a href="https://markdown.space">Markdown Space</a><br><br>
+  <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
   <a href="https://www.holloway.com">Holloway</a><br><br>
@@ -330,3 +343,2 @@ <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
 <td width="10%"></td>
-<td width="10%"></td>
 </tr>
@@ -360,5 +372,5 @@ <tr valign="middle">
 
-[size-badge]: https://img.shields.io/bundlephobia/minzip/remark-parse.svg
+[size-badge]: https://img.shields.io/bundlejs/size/remark-parse
 
-[size]: https://bundlephobia.com/result?p=remark-parse
+[size]: https://bundlejs.com/?q=remark-parse
 
@@ -391,14 +403,14 @@ [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
 [esmsh]: https://esm.sh
 
-[unified]: https://github.com/unifiedjs/unified
+[mdast]: https://github.com/syntax-tree/mdast
 
-[remark]: https://github.com/remarkjs/remark
+[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
 
-[mdast]: https://github.com/syntax-tree/mdast
+[micromark]: https://github.com/micromark/micromark
 
-[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
+[micromark-extend]: https://github.com/micromark/micromark#extensions
 
-[typescript]: https://www.typescriptlang.org
-
 [rehype]: https://github.com/rehypejs/rehype
@@ -408,8 +420,10 @@
 
-[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+[remark]: https://github.com/remarkjs/remark
 
-[micromark]: https://github.com/micromark/micromark
+[remark-core]: ../remark/
 
-[micromark-extend]: https://github.com/micromark/micromark#extensions
+[remark-directive]: https://github.com/remarkjs/remark-directive
 
+[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
+
 [remark-gfm]: https://github.com/remarkjs/remark-gfm
@@ -419,14 +433,16 @@
 
-[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
+[remark-man]: https://github.com/remarkjs/remark-man
 
 [remark-math]: https://github.com/remarkjs/remark-math
 
-[remark-man]: https://github.com/remarkjs/remark-man
+[remark-plugin]: https://github.com/remarkjs/remark#plugin
 
-[remark-directive]: https://github.com/remarkjs/remark-directive
-
 [remark-stringify]: ../remark-stringify/
 
-[remark-core]: ../remark/
+[typescript]: https://www.typescriptlang.org
 
-[plugin]: https://github.com/remarkjs/remark#plugin
+[unified]: https://github.com/unifiedjs/unified
+
+[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
+
+[api-remark-parse]: #unifieduseremarkparse

No alert changes

Improved metrics

Total package byte prevSize

19481

increased by16.03%

Lines of code

116

increased by152.17%

Number of lines in readme file

429

increased by3.87%

Worsened metrics

Dependency count

4

increased by33.33%

Dependency changes

• + Addedmicromark-util-types@^2.0.0

• + Added@types/mdast@4.0.3(transitive)

• + Added@types/unist@3.0.2(transitive)

• + Addeddevlop@1.1.0(transitive)

• + Addedmdast-util-from-markdown@2.0.0(transitive)

• + Addedmdast-util-to-string@4.0.0(transitive)

• + Addedmicromark@4.0.0(transitive)

• + Addedmicromark-core-commonmark@2.0.1(transitive)

• + Addedmicromark-factory-destination@2.0.0(transitive)

• + Addedmicromark-factory-label@2.0.0(transitive)

• + Addedmicromark-factory-space@2.0.0(transitive)

• + Addedmicromark-factory-title@2.0.0(transitive)

• + Addedmicromark-factory-whitespace@2.0.0(transitive)

• + Addedmicromark-util-character@2.1.0(transitive)

• + Addedmicromark-util-chunked@2.0.0(transitive)

• + Addedmicromark-util-classify-character@2.0.0(transitive)

• + Addedmicromark-util-combine-extensions@2.0.0(transitive)

• + Addedmicromark-util-decode-numeric-character-reference@2.0.1(transitive)

• + Addedmicromark-util-decode-string@2.0.0(transitive)

• + Addedmicromark-util-encode@2.0.0(transitive)

• + Addedmicromark-util-html-tag-name@2.0.0(transitive)

• + Addedmicromark-util-normalize-identifier@2.0.0(transitive)

• + Addedmicromark-util-resolve-all@2.0.0(transitive)

• + Addedmicromark-util-sanitize-uri@2.0.0(transitive)

• + Addedmicromark-util-subtokenize@2.0.1(transitive)

• + Addedmicromark-util-symbol@2.0.0(transitive)

• + Addedmicromark-util-types@2.0.0(transitive)

• + Addedunified@11.0.4(transitive)

• + Addedunist-util-stringify-position@4.0.0(transitive)

• + Addedvfile@6.0.1(transitive)

• + Addedvfile-message@4.0.2(transitive)

• - Removed@types/mdast@3.0.15(transitive)

• - Removed@types/unist@2.0.10(transitive)

• - Removeddiff@5.2.0(transitive)

• - Removedis-buffer@2.0.5(transitive)

• - Removedkleur@4.1.5(transitive)

• - Removedmdast-util-from-markdown@1.3.1(transitive)

• - Removedmdast-util-to-string@3.2.0(transitive)

• - Removedmicromark@3.2.0(transitive)

• - Removedmicromark-core-commonmark@1.1.0(transitive)

• - Removedmicromark-factory-destination@1.1.0(transitive)

• - Removedmicromark-factory-label@1.1.0(transitive)

• - Removedmicromark-factory-space@1.1.0(transitive)

• - Removedmicromark-factory-title@1.1.0(transitive)

• - Removedmicromark-factory-whitespace@1.1.0(transitive)

• - Removedmicromark-util-character@1.2.0(transitive)

• - Removedmicromark-util-chunked@1.1.0(transitive)

• - Removedmicromark-util-classify-character@1.1.0(transitive)

• - Removedmicromark-util-combine-extensions@1.1.0(transitive)

• - Removedmicromark-util-decode-numeric-character-reference@1.1.0(transitive)

• - Removedmicromark-util-decode-string@1.1.0(transitive)

• - Removedmicromark-util-encode@1.1.0(transitive)

• - Removedmicromark-util-html-tag-name@1.2.0(transitive)

• - Removedmicromark-util-normalize-identifier@1.1.0(transitive)

• - Removedmicromark-util-resolve-all@1.1.0(transitive)

• - Removedmicromark-util-sanitize-uri@1.2.0(transitive)

• - Removedmicromark-util-subtokenize@1.1.0(transitive)

• - Removedmicromark-util-symbol@1.1.0(transitive)

• - Removedmicromark-util-types@1.1.0(transitive)

• - Removedmri@1.2.0(transitive)

• - Removedsade@1.8.1(transitive)

• - Removedunified@10.1.2(transitive)

• - Removedunist-util-stringify-position@3.0.3(transitive)

• - Removeduvu@0.5.6(transitive)

• - Removedvfile@5.3.7(transitive)

• - Removedvfile-message@3.1.4(transitive)

• Updated@types/mdast@^4.0.0

• Updatedmdast-util-from-markdown@^2.0.0

• Updatedunified@^11.0.0