init
This commit is contained in:
4
node_modules/mdast-util-frontmatter/index.d.ts
generated
vendored
Normal file
4
node_modules/mdast-util-frontmatter/index.d.ts
generated
vendored
Normal file
@@ -0,0 +1,4 @@
|
||||
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";
|
||||
7
node_modules/mdast-util-frontmatter/index.js
generated
vendored
Normal file
7
node_modules/mdast-util-frontmatter/index.js
generated
vendored
Normal file
@@ -0,0 +1,7 @@
|
||||
/**
|
||||
* @typedef {import('./lib/index.js').Options} Options
|
||||
* @typedef {import('./lib/index.js').Matter} Matter
|
||||
* @typedef {import('./lib/index.js').Info} Info
|
||||
*/
|
||||
|
||||
export {frontmatterFromMarkdown, frontmatterToMarkdown} from './lib/index.js'
|
||||
26
node_modules/mdast-util-frontmatter/lib/index.d.ts
generated
vendored
Normal file
26
node_modules/mdast-util-frontmatter/lib/index.d.ts
generated
vendored
Normal file
@@ -0,0 +1,26 @@
|
||||
/**
|
||||
* Create an extension for `mdast-util-from-markdown`.
|
||||
*
|
||||
* @param {Options | null | undefined} [options]
|
||||
* Configuration (optional).
|
||||
* @returns {FromMarkdownExtension}
|
||||
* Extension for `mdast-util-from-markdown`.
|
||||
*/
|
||||
export function frontmatterFromMarkdown(options?: Options | null | undefined): FromMarkdownExtension;
|
||||
/**
|
||||
* Create an extension for `mdast-util-to-markdown`.
|
||||
*
|
||||
* @param {Options | null | undefined} [options]
|
||||
* Configuration (optional).
|
||||
* @returns {ToMarkdownExtension}
|
||||
* Extension for `mdast-util-to-markdown`.
|
||||
*/
|
||||
export function frontmatterToMarkdown(options?: Options | null | undefined): ToMarkdownExtension;
|
||||
export type Literal = import('mdast').Literal;
|
||||
export type CompileContext = import('mdast-util-from-markdown').CompileContext;
|
||||
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').Options;
|
||||
export type Info = import('micromark-extension-frontmatter').Info;
|
||||
export type Matter = import('micromark-extension-frontmatter').Matter;
|
||||
export type Options = import('micromark-extension-frontmatter').Options;
|
||||
176
node_modules/mdast-util-frontmatter/lib/index.js
generated
vendored
Normal file
176
node_modules/mdast-util-frontmatter/lib/index.js
generated
vendored
Normal file
@@ -0,0 +1,176 @@
|
||||
/**
|
||||
* @typedef {import('mdast').Literal} Literal
|
||||
*
|
||||
* @typedef {import('mdast-util-from-markdown').CompileContext} CompileContext
|
||||
* @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
|
||||
* @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
|
||||
* @typedef {import('mdast-util-to-markdown').Options} ToMarkdownExtension
|
||||
*
|
||||
* @typedef {import('micromark-extension-frontmatter').Info} Info
|
||||
* @typedef {import('micromark-extension-frontmatter').Matter} Matter
|
||||
* @typedef {import('micromark-extension-frontmatter').Options} Options
|
||||
*/
|
||||
|
||||
import {ok as assert} from 'devlop'
|
||||
import {toMatters} from 'micromark-extension-frontmatter'
|
||||
import escapeStringRegexp from 'escape-string-regexp'
|
||||
|
||||
/**
|
||||
* Create an extension for `mdast-util-from-markdown`.
|
||||
*
|
||||
* @param {Options | null | undefined} [options]
|
||||
* Configuration (optional).
|
||||
* @returns {FromMarkdownExtension}
|
||||
* Extension for `mdast-util-from-markdown`.
|
||||
*/
|
||||
export function frontmatterFromMarkdown(options) {
|
||||
const matters = toMatters(options)
|
||||
/** @type {FromMarkdownExtension['enter']} */
|
||||
const enter = {}
|
||||
/** @type {FromMarkdownExtension['exit']} */
|
||||
const exit = {}
|
||||
let index = -1
|
||||
|
||||
while (++index < matters.length) {
|
||||
const matter = matters[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
|
||||
|
||||
/**
|
||||
* @this {CompileContext}
|
||||
* @type {FromMarkdownHandle}
|
||||
*/
|
||||
function open(token) {
|
||||
// @ts-expect-error: custom.
|
||||
this.enter({type: matter.type, value: ''}, token)
|
||||
this.buffer()
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @this {CompileContext}
|
||||
* @type {FromMarkdownHandle}
|
||||
*/
|
||||
function close(token) {
|
||||
const data = this.resume()
|
||||
const node = this.stack[this.stack.length - 1]
|
||||
assert('value' in node)
|
||||
this.exit(token)
|
||||
// Remove the initial and final eol.
|
||||
node.value = data.replace(/^(\r?\n|\r)|(\r?\n|\r)$/g, '')
|
||||
}
|
||||
|
||||
/**
|
||||
* @this {CompileContext}
|
||||
* @type {FromMarkdownHandle}
|
||||
*/
|
||||
function value(token) {
|
||||
this.config.enter.data.call(this, token)
|
||||
this.config.exit.data.call(this, token)
|
||||
}
|
||||
|
||||
/**
|
||||
* Create an extension for `mdast-util-to-markdown`.
|
||||
*
|
||||
* @param {Options | null | undefined} [options]
|
||||
* Configuration (optional).
|
||||
* @returns {ToMarkdownExtension}
|
||||
* Extension for `mdast-util-to-markdown`.
|
||||
*/
|
||||
export function frontmatterToMarkdown(options) {
|
||||
/** @type {ToMarkdownExtension['unsafe']} */
|
||||
const unsafe = []
|
||||
/** @type {ToMarkdownExtension['handlers']} */
|
||||
const handlers = {}
|
||||
const matters = toMatters(options)
|
||||
let index = -1
|
||||
|
||||
while (++index < matters.length) {
|
||||
const matter = matters[index]
|
||||
|
||||
// @ts-expect-error: this can add custom frontmatter nodes.
|
||||
// Typing those is the responsibility of the end user.
|
||||
handlers[matter.type] = handler(matter)
|
||||
|
||||
const open = fence(matter, 'open')
|
||||
|
||||
unsafe.push({
|
||||
atBreak: true,
|
||||
character: open.charAt(0),
|
||||
after: escapeStringRegexp(open.charAt(1))
|
||||
})
|
||||
}
|
||||
|
||||
return {unsafe, handlers}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a handle that can serialize a frontmatter node as markdown.
|
||||
*
|
||||
* @param {Matter} matter
|
||||
* Structure.
|
||||
* @returns {(node: Literal) => string} enter
|
||||
* Handler.
|
||||
*/
|
||||
function handler(matter) {
|
||||
const open = fence(matter, 'open')
|
||||
const close = fence(matter, 'close')
|
||||
|
||||
return handle
|
||||
|
||||
/**
|
||||
* Serialize a frontmatter node as markdown.
|
||||
*
|
||||
* @param {Literal} node
|
||||
* Node to serialize.
|
||||
* @returns {string}
|
||||
* Serialized node.
|
||||
*/
|
||||
function handle(node) {
|
||||
return open + (node.value ? '\n' + node.value : '') + '\n' + close
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get an `open` or `close` fence.
|
||||
*
|
||||
* @param {Matter} matter
|
||||
* Structure.
|
||||
* @param {'close' | 'open'} prop
|
||||
* Field to get.
|
||||
* @returns {string}
|
||||
* Fence.
|
||||
*/
|
||||
function fence(matter, prop) {
|
||||
return matter.marker
|
||||
? pick(matter.marker, prop).repeat(3)
|
||||
: // @ts-expect-error: They’re mutually exclusive.
|
||||
pick(matter.fence, prop)
|
||||
}
|
||||
|
||||
/**
|
||||
* Take `open` or `close` fields when schema is an info object, or use the
|
||||
* given value when it is a string.
|
||||
*
|
||||
* @param {Info | string} schema
|
||||
* Info object or value.
|
||||
* @param {'close' | 'open'} prop
|
||||
* Field to get.
|
||||
* @returns {string}
|
||||
* Thing to use for the opening or closing.
|
||||
*/
|
||||
function pick(schema, prop) {
|
||||
return typeof schema === 'string' ? schema : schema[prop]
|
||||
}
|
||||
22
node_modules/mdast-util-frontmatter/license
generated
vendored
Normal file
22
node_modules/mdast-util-frontmatter/license
generated
vendored
Normal file
@@ -0,0 +1,22 @@
|
||||
(The MIT License)
|
||||
|
||||
Copyright (c) 2020 Titus Wormer <tituswormer@gmail.com>
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
'Software'), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
16
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/index.d.ts
generated
vendored
Normal file
16
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/index.d.ts
generated
vendored
Normal file
@@ -0,0 +1,16 @@
|
||||
/**
|
||||
Escape RegExp special characters.
|
||||
|
||||
You can also use this to escape a string that is inserted into the middle of a regex, for example, into a character class.
|
||||
|
||||
@example
|
||||
```
|
||||
import escapeStringRegexp from 'escape-string-regexp';
|
||||
|
||||
const escapedString = escapeStringRegexp('How much $ for a 🦄?');
|
||||
//=> 'How much \\$ for a 🦄\\?'
|
||||
|
||||
new RegExp(escapedString);
|
||||
```
|
||||
*/
|
||||
export default function escapeStringRegexp(string: string): string;
|
||||
11
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/index.js
generated
vendored
Normal file
11
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/index.js
generated
vendored
Normal file
@@ -0,0 +1,11 @@
|
||||
export default function escapeStringRegexp(string) {
|
||||
if (typeof string !== 'string') {
|
||||
throw new TypeError('Expected a string');
|
||||
}
|
||||
|
||||
// Escape characters with special meaning either inside or outside character sets.
|
||||
// Use a simple backslash escape when it’s always valid, and a `\xnn` escape when the simpler form would be disallowed by Unicode patterns’ stricter grammar.
|
||||
return string
|
||||
.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&')
|
||||
.replace(/-/g, '\\x2d');
|
||||
}
|
||||
9
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/license
generated
vendored
Normal file
9
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/license
generated
vendored
Normal file
@@ -0,0 +1,9 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
40
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/package.json
generated
vendored
Normal file
40
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/package.json
generated
vendored
Normal file
@@ -0,0 +1,40 @@
|
||||
{
|
||||
"name": "escape-string-regexp",
|
||||
"version": "5.0.0",
|
||||
"description": "Escape RegExp special characters",
|
||||
"license": "MIT",
|
||||
"repository": "sindresorhus/escape-string-regexp",
|
||||
"funding": "https://github.com/sponsors/sindresorhus",
|
||||
"author": {
|
||||
"name": "Sindre Sorhus",
|
||||
"email": "sindresorhus@gmail.com",
|
||||
"url": "https://sindresorhus.com"
|
||||
},
|
||||
"type": "module",
|
||||
"exports": "./index.js",
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
},
|
||||
"scripts": {
|
||||
"test": "xo && ava && tsd"
|
||||
},
|
||||
"files": [
|
||||
"index.js",
|
||||
"index.d.ts"
|
||||
],
|
||||
"keywords": [
|
||||
"escape",
|
||||
"regex",
|
||||
"regexp",
|
||||
"regular",
|
||||
"expression",
|
||||
"string",
|
||||
"special",
|
||||
"characters"
|
||||
],
|
||||
"devDependencies": {
|
||||
"ava": "^3.15.0",
|
||||
"tsd": "^0.14.0",
|
||||
"xo": "^0.38.2"
|
||||
}
|
||||
}
|
||||
34
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/readme.md
generated
vendored
Normal file
34
node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp/readme.md
generated
vendored
Normal file
@@ -0,0 +1,34 @@
|
||||
# escape-string-regexp
|
||||
|
||||
> Escape RegExp special characters
|
||||
|
||||
## Install
|
||||
|
||||
```
|
||||
$ npm install escape-string-regexp
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```js
|
||||
import escapeStringRegexp from 'escape-string-regexp';
|
||||
|
||||
const escapedString = escapeStringRegexp('How much $ for a 🦄?');
|
||||
//=> 'How much \\$ for a 🦄\\?'
|
||||
|
||||
new RegExp(escapedString);
|
||||
```
|
||||
|
||||
You can also use this to escape a string that is inserted into the middle of a regex, for example, into a character class.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<b>
|
||||
<a href="https://tidelift.com/subscription/pkg/npm-escape-string-regexp?utm_source=npm-escape-string-regexp&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
|
||||
</b>
|
||||
<br>
|
||||
<sub>
|
||||
Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
|
||||
</sub>
|
||||
</div>
|
||||
102
node_modules/mdast-util-frontmatter/package.json
generated
vendored
Normal file
102
node_modules/mdast-util-frontmatter/package.json
generated
vendored
Normal file
@@ -0,0 +1,102 @@
|
||||
{
|
||||
"name": "mdast-util-frontmatter",
|
||||
"version": "2.0.1",
|
||||
"description": "mdast extension to parse and serialize frontmatter (YAML, TOML, etc)",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"unist",
|
||||
"mdast",
|
||||
"mdast-util",
|
||||
"util",
|
||||
"utility",
|
||||
"markdown",
|
||||
"markup",
|
||||
"frontmatter",
|
||||
"yaml",
|
||||
"toml",
|
||||
"gfm"
|
||||
],
|
||||
"repository": "syntax-tree/mdast-util-frontmatter",
|
||||
"bugs": "https://github.com/syntax-tree/mdast-util-frontmatter/issues",
|
||||
"funding": {
|
||||
"type": "opencollective",
|
||||
"url": "https://opencollective.com/unified"
|
||||
},
|
||||
"author": "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)",
|
||||
"contributors": [
|
||||
"Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)"
|
||||
],
|
||||
"sideEffects": false,
|
||||
"type": "module",
|
||||
"exports": "./index.js",
|
||||
"files": [
|
||||
"lib/",
|
||||
"index.d.ts",
|
||||
"index.js"
|
||||
],
|
||||
"dependencies": {
|
||||
"@types/mdast": "^4.0.0",
|
||||
"devlop": "^1.0.0",
|
||||
"escape-string-regexp": "^5.0.0",
|
||||
"mdast-util-from-markdown": "^2.0.0",
|
||||
"mdast-util-to-markdown": "^2.0.0",
|
||||
"micromark-extension-frontmatter": "^2.0.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^20.0.0",
|
||||
"c8": "^8.0.0",
|
||||
"prettier": "^3.0.0",
|
||||
"remark-cli": "^11.0.0",
|
||||
"remark-preset-wooorm": "^9.0.0",
|
||||
"type-coverage": "^2.0.0",
|
||||
"typescript": "^5.0.0",
|
||||
"unist-util-remove-position": "^5.0.0",
|
||||
"xo": "^0.56.0"
|
||||
},
|
||||
"scripts": {
|
||||
"prepack": "npm run build && npm run format",
|
||||
"build": "tsc --build --clean && tsc --build && type-coverage",
|
||||
"format": "remark . -qfo && prettier . -w --log-level warn && xo --fix",
|
||||
"test-api-prod": "node --conditions production test.js",
|
||||
"test-api-dev": "node --conditions development test.js",
|
||||
"test-api": "npm run test-api-dev && npm run test-api-prod",
|
||||
"test-coverage": "c8 --100 --reporter lcov npm run test-api",
|
||||
"test": "npm run build && npm run format && npm run test-coverage"
|
||||
},
|
||||
"prettier": {
|
||||
"bracketSpacing": false,
|
||||
"semi": false,
|
||||
"singleQuote": true,
|
||||
"tabWidth": 2,
|
||||
"trailingComma": "none",
|
||||
"useTabs": false
|
||||
},
|
||||
"remarkConfig": {
|
||||
"plugins": [
|
||||
"remark-preset-wooorm"
|
||||
]
|
||||
},
|
||||
"typeCoverage": {
|
||||
"atLeast": 100,
|
||||
"detail": true,
|
||||
"ignoreCatch": true,
|
||||
"strict": true
|
||||
},
|
||||
"xo": {
|
||||
"overrides": [
|
||||
{
|
||||
"files": [
|
||||
"**/*.ts"
|
||||
],
|
||||
"rules": {
|
||||
"@typescript-eslint/consistent-type-definitions": "off"
|
||||
}
|
||||
}
|
||||
],
|
||||
"prettier": true,
|
||||
"rules": {
|
||||
"unicorn/prefer-at": "off",
|
||||
"unicorn/prefer-string-replace-all": "off"
|
||||
}
|
||||
}
|
||||
}
|
||||
414
node_modules/mdast-util-frontmatter/readme.md
generated
vendored
Normal file
414
node_modules/mdast-util-frontmatter/readme.md
generated
vendored
Normal file
@@ -0,0 +1,414 @@
|
||||
# mdast-util-frontmatter
|
||||
|
||||
[![Build][build-badge]][build]
|
||||
[![Coverage][coverage-badge]][coverage]
|
||||
[![Downloads][downloads-badge]][downloads]
|
||||
[![Size][size-badge]][size]
|
||||
[![Sponsors][sponsors-badge]][collective]
|
||||
[![Backers][backers-badge]][collective]
|
||||
[![Chat][chat-badge]][chat]
|
||||
|
||||
[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
|
||||
|
||||
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][esm].
|
||||
In Node.js (version 16+), install with [npm][]:
|
||||
|
||||
```sh
|
||||
npm install mdast-util-frontmatter
|
||||
```
|
||||
|
||||
In Deno with [`esm.sh`][esmsh]:
|
||||
|
||||
```js
|
||||
import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@2'
|
||||
```
|
||||
|
||||
In browsers with [`esm.sh`][esmsh]:
|
||||
|
||||
```html
|
||||
<script type="module">
|
||||
import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@2?bundle'
|
||||
</script>
|
||||
```
|
||||
|
||||
## Use
|
||||
|
||||
Say our document `example.md` contains:
|
||||
|
||||
```markdown
|
||||
+++
|
||||
title = "New Website"
|
||||
+++
|
||||
|
||||
# Other markdown
|
||||
```
|
||||
|
||||
…and our module `example.js` looks as follows:
|
||||
|
||||
```js
|
||||
import fs from 'node:fs/promises'
|
||||
import {frontmatter} from 'micromark-extension-frontmatter'
|
||||
import {fromMarkdown} from 'mdast-util-from-markdown'
|
||||
import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'mdast-util-frontmatter'
|
||||
import {toMarkdown} from 'mdast-util-to-markdown'
|
||||
|
||||
const doc = await fs.readFile('example.md')
|
||||
|
||||
const tree = fromMarkdown(doc, {
|
||||
extensions: [frontmatter(['yaml', 'toml'])],
|
||||
mdastExtensions: [frontmatterFromMarkdown(['yaml', 'toml'])]
|
||||
})
|
||||
|
||||
console.log(tree)
|
||||
|
||||
const out = toMarkdown(tree, {extensions: [frontmatterToMarkdown(['yaml', 'toml'])]})
|
||||
|
||||
console.log(out)
|
||||
```
|
||||
|
||||
…now running `node example.js` yields (positional info removed for brevity):
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'root',
|
||||
children: [
|
||||
{type: 'toml', value: 'title = "New Website"'},
|
||||
{
|
||||
type: 'heading',
|
||||
depth: 1,
|
||||
children: [{type: 'text', value: 'Other markdown'}]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```markdown
|
||||
+++
|
||||
title = "New Website"
|
||||
+++
|
||||
|
||||
# Other markdown
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
This package exports the identifiers
|
||||
[`frontmatterFromMarkdown`][api-frontmatter-from-markdown] and
|
||||
[`frontmatterToMarkdown`][api-frontmatter-to-markdown].
|
||||
There is no default export.
|
||||
|
||||
### `frontmatterFromMarkdown(options?)`
|
||||
|
||||
Create an extension for
|
||||
[`mdast-util-from-markdown`][mdast-util-from-markdown].
|
||||
|
||||
###### Parameters
|
||||
|
||||
* `options` ([`Options`][api-options], optional)
|
||||
— configuration
|
||||
|
||||
###### Returns
|
||||
|
||||
Extension for `mdast-util-from-markdown`
|
||||
([`FromMarkdownExtension`][from-markdown-extension]).
|
||||
|
||||
### `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`][to-markdown-extension]).
|
||||
|
||||
### `Info`
|
||||
|
||||
Structure of marker or fence (TypeScript type).
|
||||
|
||||
Same as [`Info` from `micromark-extension-frontmatter`][micromark-info].
|
||||
|
||||
### `Matter`
|
||||
|
||||
Structure of matter (TypeScript type).
|
||||
|
||||
Same as [`Matter` from `micromark-extension-frontmatter`][micromark-matter].
|
||||
|
||||
### `Options`
|
||||
|
||||
Configuration (TypeScript type).
|
||||
|
||||
Same as [`Options` from `micromark-extension-frontmatter`][micromark-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 maintained
|
||||
versions of Node.js.
|
||||
|
||||
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,
|
||||
`mdast-util-frontmatter@^2`, compatible with Node.js 16.
|
||||
|
||||
This utility works with `mdast-util-from-markdown` version 2+ and
|
||||
`mdast-util-to-markdown` version 2+.
|
||||
|
||||
## Related
|
||||
|
||||
* [`remark-frontmatter`][remark-frontmatter]
|
||||
— remark plugin to support frontmatter
|
||||
* [`micromark-extension-frontmatter`][micromark-extension-frontmatter]
|
||||
— micromark extension to parse frontmatter
|
||||
|
||||
## Contribute
|
||||
|
||||
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
|
||||
ways to get started.
|
||||
See [`support.md`][support] for ways to get help.
|
||||
|
||||
This project has a [code of conduct][coc].
|
||||
By interacting with this repository, organization, or community you agree to
|
||||
abide by its terms.
|
||||
|
||||
## License
|
||||
|
||||
[MIT][license] © [Titus Wormer][author]
|
||||
|
||||
<!-- Definitions -->
|
||||
|
||||
[build-badge]: https://github.com/syntax-tree/mdast-util-frontmatter/workflows/main/badge.svg
|
||||
|
||||
[build]: https://github.com/syntax-tree/mdast-util-frontmatter/actions
|
||||
|
||||
[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-frontmatter.svg
|
||||
|
||||
[coverage]: https://codecov.io/github/syntax-tree/mdast-util-frontmatter
|
||||
|
||||
[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-frontmatter.svg
|
||||
|
||||
[downloads]: https://www.npmjs.com/package/mdast-util-frontmatter
|
||||
|
||||
[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-frontmatter
|
||||
|
||||
[size]: https://bundlejs.com/?q=mdast-util-frontmatter
|
||||
|
||||
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
|
||||
|
||||
[backers-badge]: https://opencollective.com/unified/backers/badge.svg
|
||||
|
||||
[collective]: https://opencollective.com/unified
|
||||
|
||||
[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
|
||||
|
||||
[chat]: https://github.com/syntax-tree/unist/discussions
|
||||
|
||||
[npm]: https://docs.npmjs.com/cli/install
|
||||
|
||||
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
|
||||
|
||||
[esmsh]: https://esm.sh
|
||||
|
||||
[typescript]: https://www.typescriptlang.org
|
||||
|
||||
[license]: license
|
||||
|
||||
[author]: https://wooorm.com
|
||||
|
||||
[health]: https://github.com/syntax-tree/.github
|
||||
|
||||
[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.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-frontmatter]: https://github.com/remarkjs/remark-frontmatter
|
||||
|
||||
[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
|
||||
|
||||
[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
|
||||
|
||||
[micromark]: https://github.com/micromark/micromark
|
||||
|
||||
[micromark-extension-frontmatter]: https://github.com/micromark/micromark-extension-frontmatter
|
||||
|
||||
[micromark-info]: https://github.com/micromark/micromark-extension-frontmatter#info
|
||||
|
||||
[micromark-matter]: https://github.com/micromark/micromark-extension-frontmatter#matter
|
||||
|
||||
[micromark-options]: https://github.com/micromark/micromark-extension-frontmatter#options
|
||||
|
||||
[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
|
||||
|
||||
[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension
|
||||
|
||||
[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options
|
||||
|
||||
[dfn-frontmatter-content]: #frontmattercontent
|
||||
|
||||
[api-frontmatter-from-markdown]: #frontmatterfrommarkdownoptions
|
||||
|
||||
[api-frontmatter-to-markdown]: #frontmattertomarkdownoptions
|
||||
|
||||
[api-info]: #info
|
||||
|
||||
[api-matter]: #matter
|
||||
|
||||
[api-options]: #options
|
||||
Reference in New Issue
Block a user