diff --git a/dev/index.js b/dev/index.js index 9e7c063..ae17457 100644 --- a/dev/index.js +++ b/dev/index.js @@ -1,6 +1,9 @@ /** + * @typedef {import('./matters.js').Info} Info + * @typedef {import('./matters.js').Matter} Matter * @typedef {import('./matters.js').Options} Options + * @typedef {import('./matters.js').Preset} Preset */ -export {frontmatterHtml} from './lib/html.js' export {frontmatter} from './lib/syntax.js' +export {frontmatterHtml} from './lib/html.js' diff --git a/dev/matters.js b/dev/matters.js index 024fb00..a7bcd65 100644 --- a/dev/matters.js +++ b/dev/matters.js @@ -3,7 +3,7 @@ * Known name of a frontmatter style. * * @typedef Info - * Frontmatter style. + * Sequence. * * Depending on how this structure is used, it reflects a marker or a fence. * @property {string} open @@ -16,8 +16,8 @@ * @property {string} type * Node type to tokenize as. * @property {boolean | null | undefined} [anywhere=false] - * Whether matter can be found anywhere in the document. - * Normally, only matter at the start of the document is recognized. + * Whether matter can be found anywhere in the document, normally, only matter + * at the start of the document is recognized. * * > πŸ‘‰ **Note**: using this is a terrible idea. * > It’s called frontmatter, not matter-in-the-middle or so. diff --git a/readme.md b/readme.md index 7d4a0bd..64036f8 100644 --- a/readme.md +++ b/readme.md @@ -19,7 +19,10 @@ * [API](#api) * [`frontmatter(options?)`](#frontmatteroptions) * [`frontmatterHtml(options?)`](#frontmatterhtmloptions) + * [`Info`](#info) + * [`Matter`](#matter) * [`Options`](#options) + * [`Preset`](#preset) * [Examples](#examples) * [Authoring](#authoring) * [HTML](#html) @@ -145,6 +148,42 @@ Extension for `micromark` that can be passed in `htmlExtensions`, to support frontmatter when serializing to HTML ([`HtmlExtension`][micromark-html-extension]). +### `Info` + +Sequence (TypeScript type). + +Depending on how this structure is used, it reflects a marker or a fence. + +###### Fields + +* `open` (`string`) + β€” opening +* `close` (`string`) + β€” closing + +### `Matter` + +Fields describing a kind of matter (TypeScript type). + +> πŸ‘‰ **Note**: using `anywhere` is a terrible idea. +> It’s called frontmatter, not matter-in-the-middle or so. +> This makes your markdown less portable. + +> πŸ‘‰ **Note**: `marker` and `fence` are mutually exclusive. +> If `marker` is set, `fence` must not be set, and vice versa. + +###### Fields + +* `type` (`string`) + β€” node type to tokenize as +* `marker` (`string` or [`Info`][api-info]) + β€” character repeated 3 times, used as complete fences +* `fence` (`string` or [`Info`][api-info]) + β€” complete fences +* `anywhere` (`boolean`, default: `false`) + β€” whether matter can be found anywhere in the document, normally only + matter at the start of the document is recognized + ### `Options` Configuration (TypeScript type). @@ -155,6 +194,19 @@ Configuration (TypeScript type). type Options = Matter | Preset | Array ``` +### `Preset` + +Known name of a frontmatter style (TypeScript type). + +* `'yaml'` β€” [`Matter`][api-matter] defined as `{type: 'yaml', marker: '-'}` +* `'toml'` β€” [`Matter`][api-matter] defined as `{type: 'toml', marker: '+'}` + +###### Type + +```ts +type Preset = 'toml' | 'yaml' +``` + ## Examples Here are a couple of example of different matter objects and what frontmatter @@ -251,7 +303,8 @@ eof (end of file). ## Types This package is fully typed with [TypeScript][]. -It exports the additional type [`Options`][api-options]. +It exports the additional types [`Info`][api-info], [`Matter`][api-matter], +[`Options`][api-options], [`Preset`][api-preset]. ## Compatibility @@ -341,12 +394,18 @@ abide by its terms. [remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter +[micromark-extension]: https://github.com/micromark/micromark#syntaxextension + +[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension + [api-frontmatter]: #frontmatteroptions [api-frontmatter-html]: #frontmatterhtmloptions -[api-options]: #options +[api-info]: #info -[micromark-extension]: https://github.com/micromark/micromark#syntaxextension +[api-matter]: #matter -[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension +[api-options]: #options + +[api-preset]: #preset