Add improved docs

Author: wooorm

lib/index.js

@@ -46,8 +46,11 @@ const empty = []
  * Truncate the tree to a certain number of characters.
  *
  * @template {Node} Tree
+ *   Type of tree.
  * @param {Tree} tree
+ *   Tree to truncate.
  * @param {Options | null | undefined} [options]
+ *   Configuration (optional).
  * @returns {Tree}
  *   A shallow copy of `tree`, truncated.
  */

readme.md

@@ -17,7 +17,8 @@
 *   [Install](#install)
 *   [Use](#use)
 *   [API](#api)
-    *   [`truncate(tree, options?)`](#truncatetree-options)
+    *   [`truncate(tree[, options])`](#truncatetree-options)
+    *   [`Options`](#options)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
 *   [Security](#security)
@@ -47,7 +48,7 @@ document, for use with [`rehype-meta`][rehype-meta].
 ## Install
 
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+In Node.js (version 14.14+ or 16.0+), install with [npm][]:
 
 ```sh
 npm install hast-util-truncate
@@ -109,16 +110,29 @@ console.log(truncate(tree, {ellipsis: '…'}));
 
 ## API
 
-This package exports the identifier `truncate`.
+This package exports the identifier [`truncate`][truncate].
 There is no default export.
 
-### `truncate(tree, options?)`
+### `truncate(tree[, options])`
 
 Truncate the tree to a certain number of characters.
 
-##### `options`
+###### Parameters
 
-Configuration (optional).
+*   `tree` ([`Node`][node])
+    — tree to truncate
+*   `options` ([`Options`][options], optional)
+    — configuration
+
+###### Returns
+
+Truncated copy of `tree` ([`Node`][node]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+##### Fields
 
 ###### `options.size`
 
@@ -149,27 +163,23 @@ Set `maxCharacterStrip: 0` to not find a nice break.
 Nodes to exclude from the resulting tree (`Array<Node>`).
 These are not counted towards `size`.
 
-###### Returns
-
-Truncated copy of `tree` (`Node`).
-
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the additional type `Options`.
+It exports the additional type [`Options`][options].
 
 ## Compatibility
 
 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+, and 16.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.
 
 ## Security
 
 Use of `hast-util-truncate` should be safe if the tree is already safe and
 you’re not using user content in options.
-When in doubt, use [`hast-util-sanitize`][sanitize].
+When in doubt, use [`hast-util-sanitize`][hast-util-sanitize].
 
 ## Related
 
@@ -242,12 +252,18 @@ abide by its terms.
 
 [coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
 
-[sanitize]: https://github.com/syntax-tree/hast-util-sanitize
-
 [hast]: https://github.com/syntax-tree/hast
 
+[node]: https://github.com/syntax-tree/hast#nodes
+
+[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
+
 [hast-util-excerpt]: https://github.com/syntax-tree/hast-util-excerpt
 
 [rehype-infer-description-meta]: https://github.com/rehypejs/rehype-infer-description-meta
 
 [rehype-meta]: https://github.com/rehypejs/rehype-meta
+
+[truncate]: #truncatetree-options
+
+[options]: #options