From b685b0006004b83b685004671e81f47dbe944e9b Mon Sep 17 00:00:00 2001
From: Titus Wormer <tituswormer@gmail.com>
Date: Wed, 22 Jan 2025 16:13:18 +0100
Subject: [PATCH] Add types, docs for options

---
 .gitignore    |  1 +
 index.d.ts    | 15 +++++++++++++++
 index.js      |  1 +
 package.json  | 23 +++++++++++++++++++++++
 readme.md     | 37 +++++++++++++++++++++++++++++++++----
 tsconfig.json |  2 +-
 6 files changed, 74 insertions(+), 5 deletions(-)
 create mode 100644 index.d.ts

diff --git a/.gitignore b/.gitignore
index 388388c..8123c9e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,4 @@
 coverage/
 node_modules/
 yarn.lock
+!/index.d.ts
diff --git a/index.d.ts b/index.d.ts
new file mode 100644
index 0000000..8cd8663
--- /dev/null
+++ b/index.d.ts
@@ -0,0 +1,15 @@
+import type {ToMarkdownOptions} from 'mdast-util-directive'
+
+export {default} from './lib/index.js'
+
+/**
+ * Configuration for `remark-directive`.
+ *
+ * Currently supports
+ * `collapseEmptyAttributes`,
+ * `preferShortcut`,
+ * `preferUnquoted`,
+ * `quoteSmart`,
+ * and `quote` as serialization options.
+ */
+export interface Options extends ToMarkdownOptions {}
diff --git a/index.js b/index.js
index dab322b..6a4c25d 100644
--- a/index.js
+++ b/index.js
@@ -1 +1,2 @@
+// Note: types exposed from `index.d.ts`.
 export {default} from './lib/index.js'
diff --git a/package.json b/package.json
index 8972c2f..afa9059 100644
--- a/package.json
+++ b/package.json
@@ -78,6 +78,29 @@
   "version": "3.0.0",
   "xo": {
     "overrides": [
+      {
+        "files": [
+          "**/*.d.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/array-type": [
+            "error",
+            {
+              "default": "generic"
+            }
+          ],
+          "@typescript-eslint/ban-types": [
+            "error",
+            {
+              "extendDefaults": true
+            }
+          ],
+          "@typescript-eslint/consistent-type-definitions": [
+            "error",
+            "interface"
+          ]
+        }
+      },
       {
         "files": [
           "test/**/*.js"
diff --git a/readme.md b/readme.md
index f7ec39d..67bacb6 100644
--- a/readme.md
+++ b/readme.md
@@ -19,7 +19,8 @@ proposal][commonmark-prop] (`:cite[smith04]`,
 * [Install](#install)
 * [Use](#use)
 * [API](#api)
-  * [`unified().use(remarkDirective)`](#unifieduseremarkdirective)
+  * [`unified().use(remarkDirective[, options])`](#unifieduseremarkdirective-options)
+  * [`Options`](#options)
 * [Examples](#examples)
   * [Example: YouTube](#example-youtube)
   * [Example: Styled blocks](#example-styled-blocks)
@@ -174,13 +175,14 @@ function myRemarkPlugin() {
 This package exports no identifiers.
 The default export is [`remarkDirective`][api-remark-directive].
 
-### `unified().use(remarkDirective)`
+### `unified().use(remarkDirective[, options])`
 
 Add support for generic directives.
 
 ###### Parameters
 
-There are no parameters.
+* `options` ([`Options`][api-options], optional)
+  — configuration
 
 ###### Returns
 
@@ -191,6 +193,29 @@ Nothing (`undefined`).
 Doesn’t handle the directives:
 [create your own plugin][unified-create-plugin] to do that.
 
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `collapseEmptyAttributes`
+  (`boolean`, default: `true`)
+  — collapse empty attributes: get `title` instead of `title=""`
+* `preferShortcut`
+  (`boolean`, default: `true`)
+  — prefer `#` and `.` shortcuts for `id` and `class`
+* `preferUnquoted`
+  (`boolean`, default: `false`)
+  — leave attributes unquoted if that results in less bytes
+* `quoteSmart`
+  (`boolean`, default: `false`)
+  — use the other quote if that results in less bytes
+* `quote`
+  (`'"'` or `"'"`,
+  default: the [`quote`][quote] used by `remark-stringify` for titles)
+  — preferred quote to use around attribute values
+
 ## Examples
 
 ### Example: YouTube
@@ -500,6 +525,8 @@ abide by its terms.
 
 [micromark-extending-markdown]: https://github.com/micromark/micromark#extending-markdown
 
+[quote]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#options
+
 [rehype]: https://github.com/rehypejs/rehype
 
 [remark]: https://github.com/remarkjs/remark
@@ -512,4 +539,6 @@ abide by its terms.
 
 [wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
 
-[api-remark-directive]: #unifieduseremarkdirective
+[api-remark-directive]: #unifieduseremarkdirective-options
+
+[api-options]: #options
diff --git a/tsconfig.json b/tsconfig.json
index fc3d1e4..c3e0c82 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -12,5 +12,5 @@
     "target": "es2022"
   },
   "exclude": ["coverage/", "node_modules/"],
-  "include": ["**/*.js"]
+  "include": ["**/*.js", "index.d.ts"]
 }