From 019852e3c800f64cacddec0494a3e48ee1b72d69 Mon Sep 17 00:00:00 2001
From: Titus Wormer <tituswormer@gmail.com>
Date: Wed, 29 Mar 2023 14:16:47 +0200
Subject: [PATCH] Add exports of `Info`, `Matter`, `Preset` types

---
 dev/index.js   |  5 +++-
 dev/matters.js |  6 ++---
 readme.md      | 67 +++++++++++++++++++++++++++++++++++++++++++++++---
 3 files changed, 70 insertions(+), 8 deletions(-)

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<Matter | Preset>
 ```
 
+### `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