Add improved docs

lib/index.js

@@ -17,34 +17,34 @@
  * @typedef {Prettify<ParseOptions & DocumentOptions & SchemaOptions & ToJsOptions>} YamlOptions
  *   Options for the YAML parser.
  *
+ *   Equivalent to `ParseOptions`, `DocumentOptions`, `SchemaOptions`, and `ToJsOptions`.
+ *
  * @typedef Options
  *   Configuration (optional).
  * @property {boolean | null | undefined} [strip=false]
  *   Remove the YAML front matter from the file.
  * @property {YamlOptions | null | undefined} [yaml]
- *   Options for the YAML parser.
- *
- *   These are passed as `x` in `yaml.parse('', x)`, which is equivalent to
- *   `ParseOptions`, `DocumentOptions`, `SchemaOptions`, and `ToJsOptions`.
+ *   Configuration for the YAML parser, passed to `yaml` as `x` in
+ *   `yaml.parse('', x)`.
  */
 
 import buffer from 'is-buffer'
 import yaml from 'yaml'
 
 /**
- * Parse the YAML front matter in a `vfile` and expose it as `file.data.matter`.
+ * Parse the YAML front matter in a file and expose it as `file.data.matter`.
  *
  * If no matter is found in the file, nothing happens, except that
  * `file.data.matter` is set to an empty object (`{}`).
  *
  * @template {VFile} File
  *   File type.
  * @param {File} file
- *   Virtual file
+ *   Virtual file.
  * @param {Options | null | undefined} [options]
- *   Options
+ *   Configuration.
  * @returns {File}
- *   The given `file`
+ *   The given `file`.
  */
 // To do: next major: don’t return given file.
 export function matter(file, options) {

readme.md

@@ -18,6 +18,8 @@
 *   [Use](#use)
 *   [API](#api)
     *   [`matter(file[, options])`](#matterfile-options)
+    *   [`Options`](#options)
+    *   [`YamlOptions`](#yamloptions)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
 *   [Contribute](#contribute)
@@ -47,7 +49,7 @@ stripping frontmatter.
 ## Install
 
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with [npm][]:
+In Node.js (version 14.14+ and 16.0+), install with [npm][]:
 
 ```sh
 npm install vfile-matter
@@ -104,52 +106,72 @@ console.log(String(file))
 
 ## API
 
-This package exports the identifier `matter`.
+This package exports the identifier [`matter`][api-matter].
 There is no default export.
 
 ### `matter(file[, options])`
 
-Parse the YAML front matter in a [`vfile`][vfile], and add it as
-`file.data.matter`.
+Parse the YAML front matter in a file and expose it as `file.data.matter`.
 
 If no matter is found in the file, nothing happens, except that
 `file.data.matter` is set to an empty object (`{}`).
 
-##### `options`
+###### Parameters
+
+*   `file` ([`VFile`][vfile])
+    — virtual file
+*   `options` ([`Options`][api-options], optional)
+    — configuration
+
+###### Returns
+
+The given file ([`VFile`][vfile]).
+
+### `Options`
+
+Configuration (TypeScript type).
 
-Configuration (optional).
+###### Fields
 
-###### `options.strip`
+*   `strip` (`boolean`, default: `false`).
+    — remove the YAML front matter from the file
+*   `yaml` ([`YamlOptions`][api-yaml-options], default: {})
+    — configuration for the YAML parser, passed to [`yaml`][yaml] as `x` in
+    `yaml.parse('', x)`
 
-Remove the YAML front matter from the file (`boolean`, default: `false`).
+### `YamlOptions`
 
-###### `options.yaml`
+Options for the YAML parser (TypeScript type).
 
-Options for the YAML parser (default: `{}`).
-These are passed to [`yaml`][yaml] as `x` in `yaml.parse('', x)`, which is
-equivalent to the combination of
+Equivalent to the combination of
 [`ParseOptions`](https://eemeli.org/yaml/#parse-options),
 [`DocumentOptions`](https://eemeli.org/yaml/#document-options),
 [`SchemaOptions`](https://eemeli.org/yaml/#schema-options), and
 [`ToJsOptions`](https://eemeli.org/yaml/#tojs-options).
 
-###### Returns
+###### Type
 
-The given `file` ([`VFile`][vfile]).
+```ts
+type YamlOptions = ParseOptions &
+  DocumentOptions &
+  SchemaOptions &
+  ToJsOptions
+```
 
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the additional types `YamlOptions` and `Options`.
+It exports the additional types [`Options`][api-options] and
+[`YamlOptions`][api-yaml-options].
 
 To type `file.data.matter`, you can augment `DataMap` from `vfile` as follows:
 
 ```ts
 declare module 'vfile' {
   interface DataMap {
     matter: {
-      // `file.data.matter.string` is typed as `string?`.
-      title?: string
+      // `file.data.matter.string` is typed as `string | undefined`.
+      title?: string | undefined
     }
   }
 }
@@ -159,7 +181,7 @@ declare module 'vfile' {
 
 Projects maintained by the unified collective are compatible with all maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
+As of now, that is Node.js 14.14+ and 16.0+.
 Our projects sometimes work with older versions, but this is not guaranteed.
 
 ## Contribute
@@ -231,3 +253,9 @@ abide by its terms.
 [remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
 
 [yaml]: https://github.com/eemeli/yaml
+
+[api-matter]: #matterfile-options
+
+[api-options]: #options
+
+[api-yaml-options]: #yamloptions