mdast-util-frontmatter - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

index.d.ts

@@ -1,30 +0,4 @@
-/**
- * @param {Options} [options]
- * @returns {FromMarkdownExtension}
- */
-export function frontmatterFromMarkdown(
-  options?:
-    | import('micromark-extension-frontmatter/matters.js').Options
-    | undefined
-): FromMarkdownExtension
-/**
- * @param {Options} [options]
- * @returns {ToMarkdownExtension}
- */
-export function frontmatterToMarkdown(
-  options?:
-    | import('micromark-extension-frontmatter/matters.js').Options
-    | undefined
-): ToMarkdownExtension
-export type Literal = import('mdast').Literal
-export type FromMarkdownExtension = import('mdast-util-from-markdown').Extension
-export type FromMarkdownHandle = import('mdast-util-from-markdown').Handle
-export type ToMarkdownExtension =
-  import('mdast-util-to-markdown/lib/types.js').Options
-export type ToMarkdownHandle =
-  import('mdast-util-to-markdown/lib/types.js').Handle
-export type Map = import('mdast-util-to-markdown/lib/util/indent-lines.js').Map
-export type Options =
-  import('micromark-extension-frontmatter/matters.js').Options
-export type Matter = import('micromark-extension-frontmatter/matters.js').Matter
-export type Info = import('micromark-extension-frontmatter/matters.js').Info
+export type Options = import('./lib/index.js').Options
+export type Matter = import('./lib/index.js').Matter
+export type Info = import('./lib/index.js').Info
+export {frontmatterFromMarkdown, frontmatterToMarkdown} from './lib/index.js'

index.js

 /**
- * @typedef {import('mdast').Literal} Literal
- * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
- * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
- * @typedef {import('mdast-util-to-markdown/lib/types.js').Options} ToMarkdownExtension
- * @typedef {import('mdast-util-to-markdown/lib/types.js').Handle} ToMarkdownHandle
- * @typedef {import('mdast-util-to-markdown/lib/util/indent-lines.js').Map} Map
- *
- * @typedef {import('micromark-extension-frontmatter/matters.js').Options} Options
- * @typedef {import('micromark-extension-frontmatter/matters.js').Matter} Matter
- * @typedef {import('micromark-extension-frontmatter/matters.js').Info} Info
+ * @typedef {import('./lib/index.js').Options} Options
+ * @typedef {import('./lib/index.js').Matter} Matter
+ * @typedef {import('./lib/index.js').Info} Info
  */
 
-import {matters} from 'micromark-extension-frontmatter/matters.js'
-
-/**
- * @param {Options} [options]
- * @returns {FromMarkdownExtension}
- */
-export function frontmatterFromMarkdown(options) {
-  const settings = matters(options)
-  /** @type {FromMarkdownExtension['enter']} */
-  const enter = {}
-  /** @type {FromMarkdownExtension['exit']} */
-  const exit = {}
-  let index = -1
-
-  while (++index < settings.length) {
-    const matter = settings[index]
-    enter[matter.type] = opener(matter)
-    exit[matter.type] = close
-    exit[matter.type + 'Value'] = value
-  }
-
-  return {enter, exit}
-}
-
-/**
- * @param {Matter} matter
- * @returns {FromMarkdownHandle} enter
- */
-function opener(matter) {
-  return open
-  /** @type {FromMarkdownHandle} */
-  function open(token) {
-    // @ts-expect-error: custom.
-    this.enter({type: matter.type, value: ''}, token)
-    this.buffer()
-  }
-}
-
-/** @type {FromMarkdownHandle} */
-function close(token) {
-  const data = this.resume()
-  // Remove the initial and final eol.
-  this.exit(token).value = data.replace(/^(\r?\n|\r)|(\r?\n|\r)$/g, '')
-}
-
-/** @type {FromMarkdownHandle} */
-function value(token) {
-  this.config.enter.data.call(this, token)
-  this.config.exit.data.call(this, token)
-}
-
-/**
- * @param {Options} [options]
- * @returns {ToMarkdownExtension}
- */
-export function frontmatterToMarkdown(options) {
-  /** @type {ToMarkdownExtension['unsafe']} */
-  const unsafe = []
-  /** @type {ToMarkdownExtension['handlers']} */
-  const handlers = {}
-  const settings = matters(options)
-  let index = -1
-
-  while (++index < settings.length) {
-    const matter = settings[index]
-    handlers[matter.type] = handler(matter)
-    unsafe.push({atBreak: true, character: fence(matter, 'open').charAt(0)})
-  }
-
-  return {unsafe, handlers}
-}
-
-/**
- * @param {Matter} matter
- * @returns {(node: Literal) => string} enter
- */
-function handler(matter) {
-  const open = fence(matter, 'open')
-  const close = fence(matter, 'close')
-
-  return handle
-
-  /**
-   * @type {ToMarkdownHandle}
-   * @param {Literal} node
-   */
-  function handle(node) {
-    return open + (node.value ? '\n' + node.value : '') + '\n' + close
-  }
-}
-
-/**
- * @param {Matter} matter
- * @param {'open'|'close'} prop
- * @returns {string}
- */
-function fence(matter, prop) {
-  return matter.marker
-    ? pick(matter.marker, prop).repeat(3)
-    : // @ts-expect-error: They’re mutually exclusive.
-      pick(matter.fence, prop)
-}
-
-/**
- * @param {Info|string} schema
- * @param {'open'|'close'} prop
- * @returns {string}
- */
-function pick(schema, prop) {
-  return typeof schema === 'string' ? schema : schema[prop]
-}
+export {frontmatterFromMarkdown, frontmatterToMarkdown} from './lib/index.js'

package.json

 {
   "name": "mdast-util-frontmatter",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "mdast extension to parse and serialize frontmatter (YAML, TOML, etc)",
@@ -34,2 +34,3 @@ "license": "MIT",
   "files": [
+    "lib/",
     "index.d.ts",
@@ -39,24 +40,24 @@ "index.js"
   "dependencies": {
+    "@types/mdast": "^3.0.0",
+    "mdast-util-to-markdown": "^1.3.0",
     "micromark-extension-frontmatter": "^1.0.0"
   },
   "devDependencies": {
-    "@types/tape": "^4.0.0",
+    "@types/node": "^18.0.0",
     "c8": "^7.0.0",
     "mdast-util-from-markdown": "^1.0.0",
-    "mdast-util-to-markdown": "^1.0.0",
     "prettier": "^2.0.0",
-    "remark-cli": "^9.0.0",
-    "remark-preset-wooorm": "^8.0.0",
-    "rimraf": "^3.0.0",
-    "tape": "^5.0.0",
+    "remark-cli": "^10.0.0",
+    "remark-preset-wooorm": "^9.0.0",
     "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
     "unist-util-remove-position": "^4.0.0",
-    "xo": "^0.39.0"
+    "xo": "^0.49.0"
   },
   "scripts": {
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
+    "prepack": "npm run build && npm run format",
+    "build": "tsc --build --clean && tsc --build && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node --conditions development test.js",
-    "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node --conditions development test.js",
+    "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api",
     "test": "npm run build && npm run format && npm run test-coverage"
@@ -63,0 +64,0 @@ },

readme.md

@@ -11,21 +11,65 @@ # mdast-util-frontmatter
 
-Extension for [`mdast-util-from-markdown`][from-markdown] and/or
-[`mdast-util-to-markdown`][to-markdown] to support frontmatter in **[mdast][]**.
-When parsing (`from-markdown`), must be combined with
-[`micromark-extension-frontmatter`][extension].
+[mdast][] extensions to parse and serialize frontmatter (YAML, TOML, and more).
 
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When to use this](#when-to-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`frontmatterFromMarkdown(options?)`](#frontmatterfrommarkdownoptions)
+    *   [`frontmatterToMarkdown(options?)`](#frontmattertomarkdownoptions)
+    *   [`Info`](#info)
+    *   [`Matter`](#matter)
+    *   [`Options`](#options)
+*   [Syntax](#syntax)
+*   [Syntax tree](#syntax-tree)
+    *   [Nodes](#nodes)
+    *   [Content model](#content-model)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package contains two extensions that add support for frontmatter syntax
+as often used in markdown to [mdast][].
+These extensions plug into
+[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
+frontmatter in markdown into a syntax tree) and
+[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
+frontmatter in syntax trees to markdown).
+
+Frontmatter is a metadata format in front of the content.
+It’s typically written in YAML and is often used with markdown.
+Frontmatter does not work everywhere so it makes markdown less portable.
+
+These extensions follow how GitHub handles frontmatter.
+GitHub only supports YAML frontmatter, but these extensions also support
+different flavors (such as TOML).
+
 ## When to use this
 
-Use this if you’re dealing with the AST manually.
-It’s probably nicer to use [`remark-frontmatter`][remark-frontmatter] with
-**[remark][]**, which includes this but provides a nicer interface and
-makes it easier to combine with hundreds of plugins.
+You can use these extensions when you are working with
+`mdast-util-from-markdown` and `mdast-util-to-markdown` already.
 
+When working with `mdast-util-from-markdown`, you must combine this package
+with [`micromark-extension-frontmatter`][micromark-extension-frontmatter].
+
+When you don’t need a syntax tree, you can use [`micromark`][micromark]
+directly with
+[`micromark-extension-frontmatter`][micromark-extension-frontmatter].
+
+All these packages are used [`remark-frontmatter`][remark-frontmatter], which
+focusses on making it easier to transform content by abstracting these
+internals away.
+
 ## Install
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
-Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
+This package is [ESM only][esm].
+In Node.js (version 14.14+ and 16.0+), install with [npm][]:
 
-[npm][]:
-
 ```sh
@@ -35,5 +79,19 @@ npm install mdast-util-frontmatter
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@1'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@1?bundle'
+</script>
+```
+
 ## Use
 
-Say we have the following file, `example.md`:
+Say our document `example.md` contains:
 
@@ -48,6 +106,6 @@ ```markdown
 
-And our module, `example.js`, looks as follows:
+…and our module `example.js` looks as follows:
 
 ```js
-import fs from 'node:fs'
+import fs from 'node:fs/promises'
 import {fromMarkdown} from 'mdast-util-from-markdown'
@@ -58,3 +116,3 @@ import {toMarkdown} from 'mdast-util-to-markdown'
 
-const doc = fs.readFileSync('example.md')
+const doc = await fs.readFile('example.md')
 
@@ -73,3 +131,3 @@ const tree = fromMarkdown(doc, {
 
-Now, running `node example` yields:
+…now running `node example.js` yields (positional info removed for brevity):
 
@@ -100,36 +158,164 @@ ```js
 
-This package exports the following identifiers: `frontmatterFromMarkdown`,
-`frontmatterToMarkdown`.
+This package exports the identifiers
+[`frontmatterFromMarkdown`][api-frontmatterfrommarkdown] and
+[`frontmatterToMarkdown`][api-frontmattertomarkdown].
 There is no default export.
 
-### `frontmatterFromMarkdown([options])`
+### `frontmatterFromMarkdown(options?)`
 
-### `frontmatterToMarkdown([options])`
+Create an extension for
+[`mdast-util-from-markdown`][mdast-util-from-markdown].
 
-Support frontmatter (YAML, TOML, and more).
-These functions can be called with options and return extensions, respectively
-for [`mdast-util-from-markdown`][from-markdown] and
-[`mdast-util-to-markdown`][to-markdown].
+###### Parameters
 
-Options are the same as [`micromark-extension-frontmatter`][options].
+*   `options` ([`Options`][api-options], optional)
+    — configuration
 
+###### Returns
+
+Extension for `mdast-util-from-markdown`
+([`FromMarkdownExtension`][frommarkdownextension]).
+
+### `frontmatterToMarkdown(options?)`
+
+Create an extension for
+[`mdast-util-to-markdown`][mdast-util-to-markdown].
+
+###### Parameters
+
+*   `options` ([`Options`][api-options], optional)
+    — configuration
+
+###### Returns
+
+Extension for `mdast-util-to-markdown`
+([`ToMarkdownExtension`][tomarkdownextension]).
+
+### `Info`
+
+Structure of marker or fence (TypeScript type).
+
+<!-- To do: fix link when `info` is documented -->
+
+Same as [`Info` from `micromark-extension-frontmatter`][matter].
+
+### `Matter`
+
+Structure of matter (TypeScript type).
+
+Same as [`Matter` from `micromark-extension-frontmatter`][matter].
+
+### `Options`
+
+Configuration (TypeScript type).
+
+Same as [`Options` from `micromark-extension-frontmatter`][options].
+
+## Syntax
+
+See [Syntax in `micromark-extension-frontmatter`][syntax].
+
+## Syntax tree
+
+The following interfaces are added to **[mdast][]** by this utility.
+
+### Nodes
+
+> 👉 **Note**: other nodes are not enabled by default, but when passing options
+> to enable them, they work the same as YAML.
+
+#### `YAML`
+
+```idl
+interface YAML <: Literal {
+  type: "yaml"
+}
+```
+
+**YAML** (**[Literal][dfn-literal]**) represents a collection of metadata for
+the document in the YAML data serialization language.
+
+**YAML** can be used where **[frontmatter][dfn-frontmatter-content]** content
+is expected.
+Its content is represented by its `value` field.
+
+For example, the following markdown:
+
+```markdown
+---
+foo: bar
+---
+```
+
+Yields:
+
+```js
+{type: 'yaml', value: 'foo: bar'}
+```
+
+### Content model
+
+#### `FrontmatterContent`
+
+```idl
+type FrontmatterContent = YAML
+```
+
+**Frontmatter** content represent out-of-band information about the document.
+
+If frontmatter is present, it must be limited to one node in the
+*[tree][term-tree]*, and can only exist as a *[head][term-head]*.
+
+#### `FlowContent` (frontmatter)
+
+```idl
+type FlowContentFrontmatter = FrontmatterContent | FlowContent
+```
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional types [`Info`][api-info], [`Matter`][api-matter],
+and [`Options`][api-options].
+
+The YAML node type is supported in `@types/mdast` by default.
+To add other node types, register them by adding them to
+`FrontmatterContentMap`:
+
+```ts
+import type {Literal} from 'mdast'
+
+interface Toml extends Literal {
+  type: 'toml'
+}
+
+declare module 'mdast' {
+  interface FrontmatterContentMap {
+    // Allow using TOML nodes defined by `mdast-util-frontmatter`.
+    toml: Toml
+  }
+}
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with all maintained
+versions of Node.js.
+As of now, that is Node.js 14.14+ and 16.0+.
+Our projects sometimes work with older versions, but this is not guaranteed.
+
+These extensions works with `mdast-util-from-markdown` version 1+ and
+`mdast-util-to-markdown` version 1+.
+
 ## Related
 
-*   [`remarkjs/remark`][remark]
-    — markdown processor powered by plugins
-*   [`remarkjs/remark-frontmatter`][remark-frontmatter]
+*   [`remark-frontmatter`][remark-frontmatter]
     — remark plugin to support frontmatter
-*   [`micromark/micromark`][micromark]
-    — the smallest commonmark-compliant markdown parser that exists
-*   [`micromark/micromark-extension-frontmatter`][extension]
+*   [`micromark-extension-frontmatter`][micromark-extension-frontmatter]
     — micromark extension to parse frontmatter
-*   [`syntax-tree/mdast-util-from-markdown`][from-markdown]
-    — mdast parser using `micromark` to create mdast from markdown
-*   [`syntax-tree/mdast-util-to-markdown`][to-markdown]
-    — mdast serializer to create markdown from mdast
 
 ## Contribute
 
-See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
-started.
+See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
+ways to get started.
 See [`support.md`][support] for ways to get help.
@@ -175,2 +361,8 @@
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
+
 [license]: license
@@ -180,22 +372,48 @@
 
-[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
+[health]: https://github.com/syntax-tree/.github
 
-[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
+[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
 
-[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
+[support]: https://github.com/syntax-tree/.github/blob/main/support.md
 
+[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
+
 [mdast]: https://github.com/syntax-tree/mdast
 
-[remark]: https://github.com/remarkjs/remark
-
 [remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
 
-[from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
 
-[to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
+[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
 
 [micromark]: https://github.com/micromark/micromark
 
-[extension]: https://github.com/micromark/micromark-extension-frontmatter
+[micromark-extension-frontmatter]: https://github.com/micromark/micromark-extension-frontmatter
 
 [options]: https://github.com/micromark/micromark-extension-frontmatter#options
+
+[matter]: https://github.com/micromark/micromark-extension-frontmatter#matter
+
+[syntax]: https://github.com/micromark/micromark-extension-frontmatter#syntax
+
+[dfn-literal]: https://github.com/syntax-tree/mdast#literal
+
+[term-tree]: https://github.com/syntax-tree/unist#tree
+
+[term-head]: https://github.com/syntax-tree/unist#head
+
+[frommarkdownextension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension
+
+[tomarkdownextension]: https://github.com/syntax-tree/mdast-util-to-markdown#options
+
+[dfn-frontmatter-content]: #frontmattercontent
+
+[api-frontmatterfrommarkdown]: #frontmatterfrommarkdownoptions
+
+[api-frontmattertomarkdown]: #frontmattertomarkdownoptions
+
+[api-info]: #info
+
+[api-matter]: #matter
+
+[api-options]: #options

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

20259

increased by53.31%

Dev dependency count

10

decreased by-23.08%

Number of package files

7

increased by40%

Lines of code

193

increased by38.85%

Number of lines in readme file

412

increased by112.37%

Worsened metrics

Dependency count

3

increased by200%

Dependency changes

• + Added@types/mdast@^3.0.0

• + Addedmdast-util-to-markdown@^1.3.0

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

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

• + Addedcharacter-entities@2.0.2(transitive)

• + Addeddecode-named-character-reference@1.0.2(transitive)

• + Addedlongest-streak@3.1.0(transitive)

• + Addedmdast-util-phrasing@3.0.1(transitive)

• + Addedmdast-util-to-markdown@1.5.0(transitive)

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

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

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

• + Addedunist-util-is@5.2.1(transitive)

• + Addedunist-util-visit@4.1.2(transitive)

• + Addedunist-util-visit-parents@5.1.3(transitive)

• + Addedzwitch@2.0.4(transitive)