# yfm

> A simple to use YAML Front-Matter parsing and extraction Library.

Latest version **0.2.0** (published 2014-02-05) · 0 weekly downloads

## Install

```sh
npm install yfm
pnpm add yfm
yarn add yfm
bun add yfm
```

## Health

**Score 10/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; low quality score; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2014-02-05 |
| First published | 2014-02-05 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.8.0 |
| Dependencies | 4 |
| Known vulnerabilities | 0 (+12 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Jon Schlinkert |
| Maintainers | jonschlinkert |
| Keywords | front-matter, front matter, frontmatter, yaml front matter, yfm, yaml |

## Links

- npm: https://www.npmjs.com/package/yfm
- Repository: https://github.com/assemble/yfm
- Issues: https://github.com/assemble/yfm/issues
- npm.io page: https://npm.io/package/yfm

## Dependencies (4)

- [delims](https://npm.io/package/delims.md) ~0.1.0
- [lodash](https://npm.io/package/lodash.md) ~2.4.1
- [js-yaml](https://npm.io/package/js-yaml.md) ~3.0.1
- [fs-utils](https://npm.io/package/fs-utils.md) ~0.1.6

## Alternatives

- [monaco-yaml](https://npm.io/package/monaco-yaml.md) — 420.1K weekly downloads
- [@crewx/workflow](https://npm.io/package/@crewx/workflow.md) — 3.1K weekly downloads
- [yaml-cat](https://npm.io/package/yaml-cat.md) — 38 weekly downloads
- [nunjucks-in-yaml](https://npm.io/package/nunjucks-in-yaml.md) — 9 weekly downloads
- [shopify-symlinks](https://npm.io/package/shopify-symlinks.md) — 3 weekly downloads

## Recent versions

- 0.2.0 (latest) — 2014-02-05
- 0.1.1 — 2014-02-05

## README

# yfm [![NPM version](https://badge.fury.io/js/yfm.png)](http://badge.fury.io/js/yfm)

> A simple to use YAML Front-Matter parsing and extraction Library.

**Why another YAML Front Matter library?**

Because other libraries we tried failed to meet our requirements with [Assemble](http://assemble.io). Some most of the libraries met most of the requirements, but _none had all of them_. Here are the most important:

* Be usable, if not simple
* Allow custom delimiters
* Use a dependable and well-supported library for parsing YAML
* Don't fail if YAML front matter exists, but no content
* Don't fail if content exists, but no YAML front matter
* Have no problem reading YAML files directly
* Have no problem with complex content, including fenced code blocks containing examples of YAML front matter.
* Should return an object that contains the parsed YAML front matter and content, as well as the "original" content.

```bash
npm i yfm --save
```
## Usage

```js
var yfm = require('yfm');
yfm(String, Object);
```

## Methods

### yfm

By default the `yfm()` method expects a string. So this:

```js
yfm('---\nTitle: This is YFM\n---\n<p>This is content.<p>');
```

results in:

```json
{
  "context": {
    "title": "This is YFM"
  },
  "content": "<p>This is content.<p>",
  "original": "---\nTitle: This is YFM\n---\n<p>This is content.<p>"
}
```

### yfm.read

To read a file from the file system before parsing, use `yfm.read`:

```js
yfm.read('file.md');
```

### yfm.exists

To check for YAML front matter, returning `true` or `false` if it exists, use `yfm.exists`:

```js
yfm.exists('file.md');
```



## Options

> All methods will accept an options object to be passed as a second paramer

#### delimiters
Type: `object`

Default: `{delims: ['---', '---']}`

Open and close delimiters can be passed in as an array of strings. Example:

```js
yfm.read('file.md', {delims: ['~~~', '~~~']});
```

You may also pass an array of arrays, allowing multiple alternate delimiters to be used. Example:


```js
{
  delims: [
    ['---', '~~~'], ['---', '~~~']
  ]
}
```

_However, passing multiple delimiters will yield unpredictable results, so it is recommended that you use this option only for testing purposes._


## Examples

Let's say our page, `foo.html` contains

```html
---
title: YAML Front matter
description: This is a page
---
<h1>{{title}}</h1>
```

then running the following in the command line:

```js
console.log(yfm('foo.html'));
```
returns

```json
{
  "context": {
    "title": "YAML Front matter",
    "description": "This is a page"
  },
  "content": "<h1>{{title}}</h1>",
  "original": "---\ntitle: YAML Front matter\n---\n<h1>{{title}}</h1>"
}
```
and

```js
console.log(yfm('foo.html').context);
```
returns


```json
{"title": "YAML Front matter", "description": "This is a page"}
```


## Authors

**Jon Schlinkert**

+ [github/jonschlinkert](https://github.com/jonschlinkert)
+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

**Brian Woodward**

+ [github/doowb](https://github.com/doowb)
+ [twitter/doowb](http://twitter.com/jonschlinkert)


## License
Copyright (c) 2014 Jon Schlinkert, Brian Woodward, contributors.
Released under the MIT license

***

_This file was generated by [grunt-readme](https://github.com/assemble/grunt-readme) on Monday, January 27, 2014._

[grunt]: http://gruntjs.com/
[Getting Started]: https://github.com/gruntjs/grunt/blob/devel/docs/getting_started.md
[package.json]: https://npmjs.org/doc/json.html

---
_Source: https://npm.io/package/yfm · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._