UNPKG

3.77 kBMarkdownView Raw
1# remark-frontmatter [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status] [![Chat][chat-badge]][chat]
2
3Frontmatter (YAML, TOML, and more) support for [**remark**][remark].
4
5## Installation
6
7[npm][]:
8
9```bash
10npm install remark-frontmatter
11```
12
13## Usage
14
15Say we have the following file, `example.md`:
16
17```markdown
18+++
19title = "New Website"
20+++
21
22# Other markdown
23```
24
25And our script, `example.js`, looks as follows:
26
27```javascript
28var vfile = require('to-vfile');
29var report = require('vfile-reporter');
30var unified = require('unified');
31var parse = require('remark-parse');
32var stringify = require('remark-stringify');
33var frontmatter = require('remark-frontmatter');
34
35unified()
36 .use(parse)
37 .use(stringify)
38 .use(frontmatter, ['yaml', 'toml'])
39 .use(logger)
40 .process(vfile.readSync('example.md'), function (err, file) {
41 console.log(String(file));
42 console.error(report(err || file));
43 });
44
45function logger() {
46 return console.dir;
47}
48```
49
50Now, running `node example` yields:
51
52```js
53{ type: 'root',
54 children:
55 [ { type: 'toml',
56 value: 'title = "New Website"',
57 position: [Object] },
58 { type: 'heading',
59 depth: 1,
60 children: [Array],
61 position: [Object] } ],
62 position: [Object] }
63```
64
65```markdown
66example.md: no issues found
67+++
68title = "New Website"
69+++
70
71# Other markdown
72```
73
74## API
75
76### `remark.use(frontmatter[, options])`
77
78Adds [tokenizers][] if the [processor][] is configured with
79[`remark-parse`][parse], and [visitors][] if configured with
80[`remark-stringify`][stringify].
81
82If you are parsing from a different syntax, or compiling to a different syntax
83(e.g., [`remark-man`][man]) your custom nodes may not be supported.
84
85###### `options`
86
87An optional configuration array defining all the supported frontmatters
88(`Array.<preset|Matter>?`, default: `['yaml']`).
89
90###### `preset`
91
92Either `'yaml'` or `'toml'`:
93
94* `'yaml'` — [`matter`][matter] defined as `{type: 'yaml', marker: '-'}`
95* `'toml'` — [`matter`][matter] defined as `{type: 'toml', marker: '+'}`
96
97###### `Matter`
98
99An object with a `type` and a `marker`:
100
101* `type` (`string`) — Node type to parse to in [mdast][] and compile from
102* `marker` (`string`) — Character used for fences
103
104## Related
105
106* [`remark-github`](https://github.com/wooorm/remark-github)
107 — Auto-link references like in GitHub issues, PRs, and comments
108* [`remark-math`](https://github.com/rokt33r/remark-math)
109 — Math support
110* [`remark-yaml-config`](https://github.com/wooorm/remark-yaml-config)
111 — Configure remark from YAML configuration
112
113## License
114
115[MIT][license] © [Titus Wormer][author]
116
117<!-- Definitions -->
118
119[build-badge]: https://img.shields.io/travis/wooorm/remark-frontmatter.svg
120
121[build-status]: https://travis-ci.org/wooorm/remark-frontmatter
122
123[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/remark-frontmatter.svg
124
125[coverage-status]: https://codecov.io/github/wooorm/remark-frontmatter
126
127[chat-badge]: https://img.shields.io/gitter/room/wooorm/remark.svg
128
129[chat]: https://gitter.im/wooorm/remark
130
131[license]: LICENSE
132
133[author]: http://wooorm.com
134
135[npm]: https://docs.npmjs.com/cli/install
136
137[remark]: https://github.com/wooorm/remark
138
139[parse]: https://github.com/wooorm/remark/tree/master/packages/remark-parse
140
141[tokenizers]: https://github.com/wooorm/remark/tree/master/packages/remark-parse#parserblocktokenizers
142
143[stringify]: https://github.com/wooorm/remark/tree/master/packages/remark-stringify
144
145[visitors]: https://github.com/wooorm/remark/tree/master/packages/remark-stringify#compilervisitors
146
147[processor]: https://github.com/unifiedjs/unified#processor
148
149[mdast]: https://github.com/syntax-tree/mdast
150
151[matter]: #matter
152
153[man]: https://github.com/wooorm/remark-man