Skip to content

Commit

Permalink
Add improved docs
Browse files Browse the repository at this point in the history
  • Loading branch information
wooorm committed Jun 11, 2022
1 parent 1bd1da2 commit 01838d4
Showing 1 changed file with 114 additions and 22 deletions.
136 changes: 114 additions & 22 deletions readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,68 @@
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

Parse the YAML front matter in a [`vfile`][vfile].
[vfile][] utility parse YAML front matter.

## Install
## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`matter(file[, options])`](#matterfile-options)
* [Types](#types)
* [Compatibility](#compatibility)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package parses YAML frontmatter, when found in a file, and exposes it as
`file.data.matter`.
It can optionally strip the frontmatter, which is useful for languages that do
not understand frontmatter, but stripping can make it harder to deal with
languages that *do* understand it, such as markdown, because it messes up
positional info of warnings and errors.

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.
## 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.

When using vfiles with markdown, you are likely also using [remark][], in which
case you should use [`remark-frontmatter`][remark-frontmatter], instead of
stripping frontmatter.

## Install

[npm][]:
This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install vfile-matter
```

In Deno with [`esm.sh`][esmsh]:

```js
import {matter} from 'https://esm.sh/vfile-matter@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
import {matter} from 'https://esm.sh/vfile-matter@3?bundle'
</script>
```

## Use

Say we have a file, `example.html`:
Say our document `example.html` contains:

```html
---
Expand All @@ -32,21 +78,21 @@ title: Hello, world!
<p>Some more text</p>
```

And our script, `example.js`, looks like so:
…and our module `example.js` looks as follows:

```js
import {toVFile as vfile} from 'to-vfile'
import {read} from 'to-vfile'
import {matter} from 'vfile-matter'

var file = vfile.readSync('example.html')
const file = await read('example.html')

matter(file, {strip: true})

console.log(file.data)
console.log(String(file))
```

Now, running our script (`node example`) yields:
…now running `node example.js` yields:

```js
{matter: {title: 'Hello, world!'}}
Expand All @@ -58,7 +104,7 @@ Now, running our script (`node example`) yields:

## API

This package exports the following identifiers: `matter`.
This package exports the identifier `matter`.
There is no default export.

### `matter(file[, options])`
Expand All @@ -69,18 +115,52 @@ Parse the YAML front matter in a [`vfile`][vfile], and add it as
If no matter is found in the file, nothing happens, except that
`file.data.matter` is set to an empty object (`{}`).

###### Parameters
##### `options`

* `file` ([`VFile`][vfile])
— Virtual file
* `options.strip` (`boolean`, default: `false`)
— Remove the YAML front matter from the file
* `options.yaml` (`Object`, default: `{}`)
— Options passed to `jsYaml.load()`
Configuration (optional).

###### `options.strip`

Remove the YAML front matter from the file (`boolean`, default: `false`).

###### `options.yaml`

Options for the YAML parser (default: `{}`).
These are passed to [`yaml`][yaml] as `x` in `yaml.parse('', x)`, which is
equivalent to the combination of
[`ParseOptions`](https://eemeli.org/yaml/#parse-options),
[`DocumentOptions`](https://eemeli.org/yaml/#document-options),
[`SchemaOptions`](https://eemeli.org/yaml/#schema-options), and
[`ToJsOptions`](https://eemeli.org/yaml/#tojs-options).

###### Returns

The given `file`.
The given `file` ([`VFile`][vfile]).

## Types

This package is fully typed with [TypeScript][].
It exports the additional types `YamlOptions` and `Options`.

To type `file.data.matter`, you can augment `DataMap` from `vfile` as follows:

```ts
declare module 'vfile' {
interface DataMap {
matter: {
// `file.data.matter.string` is typed as `string?`.
title?: string
}
}
}
```

## 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+, 16.0+, and 18.0+.
Our projects sometimes work with older versions, but this is not guaranteed.

## Contribute

Expand Down Expand Up @@ -126,16 +206,28 @@ abide by its terms.

[npm]: https://docs.npmjs.com/cli/install

[contributing]: https://github.com/vfile/.github/blob/HEAD/contributing.md
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[support]: https://github.com/vfile/.github/blob/HEAD/support.md
[contributing]: https://github.com/vfile/.github/blob/main/contributing.md

[support]: https://github.com/vfile/.github/blob/main/support.md

[health]: https://github.com/vfile/.github

[coc]: https://github.com/vfile/.github/blob/HEAD/code-of-conduct.md
[coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md

[license]: license

[author]: https://wooorm.com

[vfile]: https://github.com/vfile/vfile

[remark]: https://github.com/remarkjs/remark

[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter

[yaml]: https://github.com/eemeli/yaml

0 comments on commit 01838d4

Please # to comment.