remark-frontmatter
Advanced tools
Comparing version 4.0.0 to 4.0.1
{ | ||
"name": "remark-frontmatter", | ||
"version": "4.0.0", | ||
"version": "4.0.1", | ||
"description": "remark plugin to support frontmatter (yaml, toml, and more)", | ||
@@ -50,3 +50,3 @@ "license": "MIT", | ||
"remark-cli": "^10.0.0", | ||
"remark-preset-wooorm": "^8.0.0", | ||
"remark-preset-wooorm": "^9.0.0", | ||
"rimraf": "^3.0.0", | ||
@@ -57,3 +57,3 @@ "tape": "^5.0.0", | ||
"typescript": "^4.0.0", | ||
"xo": "^0.43.0" | ||
"xo": "^0.45.0" | ||
}, | ||
@@ -60,0 +60,0 @@ "scripts": { |
249
readme.md
@@ -13,17 +13,51 @@ # remark-frontmatter | ||
## Important! | ||
## Contents | ||
This plugin is affected by the new parser in remark | ||
([`micromark`](https://github.com/micromark/micromark), | ||
see [`remarkjs/remark#536`](https://github.com/remarkjs/remark/pull/536)). | ||
Use version 2 while you’re still on remark 12. | ||
Use version 3 for remark 13+. | ||
* [What is this?](#what-is-this) | ||
* [When should I use this?](#when-should-i-use-this) | ||
* [Install](#install) | ||
* [Use](#use) | ||
* [API](#api) | ||
* [`unified().use(remarkFrontmatter[, options])`](#unifieduseremarkfrontmatter-options) | ||
* [Examples](#examples) | ||
* [Example: custom marker](#example-custom-marker) | ||
* [Example: custom fence](#example-custom-fence) | ||
* [Syntax](#syntax) | ||
* [Syntax tree](#syntax-tree) | ||
* [Types](#types) | ||
* [Compatibility](#compatibility) | ||
* [Security](#security) | ||
* [Related](#related) | ||
* [Contribute](#contribute) | ||
* [License](#license) | ||
## What is this? | ||
This package is a [unified][] ([remark][]) plugin to add support for YAML, TOML, | ||
and other frontmatter. | ||
You can use this to add support for parsing and serializing this syntax | ||
extension. | ||
unified is an AST (abstract syntax tree) based transform project. | ||
**remark** is everything unified that relates to markdown. | ||
The layer under remark is called mdast, which is only concerned with syntax | ||
trees. | ||
Another layer underneath is micromark, which is only concerned with parsing. | ||
This package is a small wrapper to integrate all of these. | ||
## When should I use this? | ||
Frontmatter is a metadata format in front of content. | ||
It’s typically written in YAML and is often used with markdown. | ||
This mechanism works well when you want authors, that have some markup | ||
experience, to configure where or how the content is displayed or supply | ||
metadata about content. | ||
Frontmatter does not work everywhere so it makes markdown less portable. | ||
A good example use case is markdown being rendered by (static) site generators. | ||
## 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](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). | ||
In Node.js (12.20+, 14.14+, 16.0+), install with [npm][]: | ||
[npm][]: | ||
```sh | ||
@@ -33,2 +67,16 @@ npm install remark-frontmatter | ||
In Deno with [Skypack][]: | ||
```js | ||
import remarkFrontmatter from 'https://cdn.skypack.dev/remark-frontmatter@4?dts' | ||
``` | ||
In browsers with [Skypack][]: | ||
```html | ||
<script type="module"> | ||
import remarkFrontmatter from 'https://cdn.skypack.dev/remark-frontmatter@4?min' | ||
</script> | ||
``` | ||
## Use | ||
@@ -49,4 +97,3 @@ | ||
```js | ||
import {readSync} from 'to-vfile' | ||
import {reporter} from 'vfile-reporter' | ||
import {read} from 'to-vfile' | ||
import {unified} from 'unified' | ||
@@ -57,16 +104,16 @@ import remarkParse from 'remark-parse' | ||
const file = readSync('example.md') | ||
main() | ||
unified() | ||
.use(remarkParse) | ||
.use(remarkStringify) | ||
.use(remarkFrontmatter, ['yaml', 'toml']) | ||
.use(() => (tree) => { | ||
console.dir(tree) | ||
}) | ||
.process(file) | ||
.then((file) => { | ||
console.error(reporter(file)) | ||
console.log(String(file)) | ||
}) | ||
async function main() { | ||
const file = await unified() | ||
.use(remarkParse) | ||
.use(remarkStringify) | ||
.use(remarkFrontmatter, ['yaml', 'toml']) | ||
.use(() => (tree) => { | ||
console.dir(tree) | ||
}) | ||
.process(await read('example.md')) | ||
console.log(String(file)) | ||
} | ||
``` | ||
@@ -91,3 +138,2 @@ | ||
```markdown | ||
example.md: no issues found | ||
+++ | ||
@@ -109,7 +155,131 @@ title = "New Website" | ||
and more). | ||
Doesn’t parse the data inside them: [create your own plugin][create-plugin] to | ||
do that. | ||
##### `options` | ||
See [`micromark-extension-frontmatter`][options] for a description of `options`. | ||
One `preset` or `Matter`, or an array of them, defining all the supported | ||
frontmatters (default: `'yaml'`). | ||
##### `preset` | ||
Either `'yaml'` or `'toml'`: | ||
* `'yaml'` — `Matter` defined as `{type: 'yaml', marker: '-'}` | ||
* `'toml'` — `Matter` defined as `{type: 'toml', marker: '+'}` | ||
##### `Matter` | ||
An object with a `type` and either a `marker` or a `fence`: | ||
* `type` (`string`) | ||
— Type to tokenize as | ||
* `marker` (`string` or `{open: string, close: string}`) | ||
— Character used to construct fences. | ||
By providing an object with `open` and `close` different characters can be | ||
used for opening and closing fences. | ||
For example the character `'-'` will result in `'---'` being used as the | ||
fence | ||
* `fence` (`string` or `{open: string, close: string}`) | ||
— String used as the complete fence. | ||
By providing an object with `open` and `close` different values can be used | ||
for opening and closing fences. | ||
This can be used too if fences contain different characters or lengths other | ||
than 3 | ||
* `anywhere` (`boolean`, default: `false`) | ||
– if `true`, matter can be found anywhere in the document. | ||
If `false` (default), only matter at the start of the document is recognized | ||
## Examples | ||
### Example: custom marker | ||
A custom frontmatter with different open and close markers, repeated 3 times, | ||
that looks like this: | ||
```text | ||
<<< | ||
data | ||
>>> | ||
# hi | ||
``` | ||
…can be supported with: | ||
```js | ||
// … | ||
.use(remarkFrontmatter, {type: 'custom', marker: {open: '<', close: '>'}}) | ||
// … | ||
``` | ||
### Example: custom fence | ||
A custom frontmatter with custom fences that are not repeated like this: | ||
```text | ||
{ | ||
"key": "value" | ||
} | ||
# hi | ||
``` | ||
…can be supported with: | ||
```js | ||
// … | ||
.use(remarkFrontmatter, {type: 'json', fence: {open: '{', close: '}'}}) | ||
// … | ||
``` | ||
## Syntax | ||
This plugin applies a micromark extensions to parse the syntax. | ||
See its readme for how it works: | ||
* [`micromark-extension-frontmatter`](https://github.com/micromark/micromark-extension-frontmatter) | ||
The syntax supported depends on the given configuration. | ||
## Syntax tree | ||
This plugin applies one mdast utility to build and serialize the AST. | ||
See its readme for how it works: | ||
* [`mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-directive) | ||
The node types supported in the tree depend on the given configuration. | ||
## Types | ||
This package is fully typed with [TypeScript][]. | ||
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 `remark-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 12.20+, 14.14+, and 16.0+. | ||
Our projects sometimes work with older versions, but this is not guaranteed. | ||
This plugin works with unified 6+ and remark 13+. | ||
## Security | ||
@@ -123,12 +293,13 @@ | ||
* [`remark-yaml-config`](https://github.com/remarkjs/remark-yaml-config) | ||
— configure remark from YAML configuration | ||
* [`remark-gfm`](https://github.com/remarkjs/remark-gfm) | ||
— GitHub Flavored Markdown | ||
* [`remark-footnotes`](https://github.com/remarkjs/remark-footnotes) | ||
— Footnotes | ||
— support GFM (autolink literals, strikethrough, tables, tasklists) | ||
* [`remark-github`](https://github.com/remarkjs/remark-github) | ||
— link references to commits, issues, pull-requests, and users, like on | ||
GitHub | ||
* [`remark-directive`](https://github.com/remarkjs/remark-directive) | ||
— support directives | ||
* [`remark-math`](https://github.com/remarkjs/remark-math) | ||
— Math | ||
* [`remark-github`](https://github.com/remarkjs/remark-github) | ||
— Auto-link references like in GitHub issues, PRs, and comments | ||
* [`remark-yaml-config`](https://github.com/remarkjs/remark-yaml-config) | ||
— Configure remark from YAML configuration | ||
— support math | ||
@@ -179,2 +350,4 @@ ## Contribute | ||
[skypack]: https://www.skypack.dev | ||
[health]: https://github.com/remarkjs/.github | ||
@@ -192,2 +365,4 @@ | ||
[unified]: https://github.com/unifiedjs/unified | ||
[remark]: https://github.com/remarkjs/remark | ||
@@ -197,2 +372,4 @@ | ||
[typescript]: https://www.typescriptlang.org | ||
[rehype]: https://github.com/rehypejs/rehype | ||
@@ -202,2 +379,2 @@ | ||
[options]: https://github.com/micromark/micromark-extension-frontmatter#options | ||
[create-plugin]: https://unifiedjs.com/learn/guide/create-a-plugin/ |
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
14728
370