1 | # remark-frontmatter [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status] [![Chat][chat-badge]][chat]
|
2 |
|
3 | Frontmatter (YAML, TOML, and more) support for [**remark**][remark].
|
4 |
|
5 | ## Installation
|
6 |
|
7 | [npm][]:
|
8 |
|
9 | ```bash
|
10 | npm install remark-frontmatter
|
11 | ```
|
12 |
|
13 | ## Usage
|
14 |
|
15 | Say we have the following file, `example.md`:
|
16 |
|
17 | ```markdown
|
18 | +++
|
19 | title = "New Website"
|
20 | +++
|
21 |
|
22 | # Other markdown
|
23 | ```
|
24 |
|
25 | And our script, `example.js`, looks as follows:
|
26 |
|
27 | ```javascript
|
28 | var vfile = require('to-vfile');
|
29 | var report = require('vfile-reporter');
|
30 | var unified = require('unified');
|
31 | var parse = require('remark-parse');
|
32 | var stringify = require('remark-stringify');
|
33 | var frontmatter = require('remark-frontmatter');
|
34 |
|
35 | unified()
|
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 |
|
45 | function logger() {
|
46 | return console.dir;
|
47 | }
|
48 | ```
|
49 |
|
50 | Now, 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
|
66 | example.md: no issues found
|
67 | +++
|
68 | title = "New Website"
|
69 | +++
|
70 |
|
71 | # Other markdown
|
72 | ```
|
73 |
|
74 | ## API
|
75 |
|
76 | ### `remark.use(frontmatter[, options])`
|
77 |
|
78 | Adds [tokenizers][] if the [processor][] is configured with
|
79 | [`remark-parse`][parse], and [visitors][] if configured with
|
80 | [`remark-stringify`][stringify].
|
81 |
|
82 | If 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 |
|
87 | An optional configuration array defining all the supported frontmatters
|
88 | (`Array.<preset|Matter>?`, default: `['yaml']`).
|
89 |
|
90 | ###### `preset`
|
91 |
|
92 | Either `'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 |
|
99 | An 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 |
|
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
|