From ffabde357f05e55986b4cceafa12de0ec24ccc19 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 14:34:32 +0900
Subject: [PATCH 01/19] add link to yaml, toml, json specs

---
 front_matter/create_extractor.ts | 3 ++-
 front_matter/test.ts             | 4 +++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index 411abdd4cdc1..7908c9c1e443 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -73,7 +73,8 @@ function recognize(str: string, formats?: Format[]): Format {
 
 /**
  * Factory that creates a function that extracts front matter from a string with the given parsers.
- * Supports YAML, TOML and JSON.
+ * Supports {@link https://yaml.org | YAML}, {@link https://toml.io | TOML} and
+ * {@link https://www.json.org/ | JSON}.
  *
  * @param formats A descriptor containing Format-parser pairs to use for each format.
  * @returns A function that extracts front matter from a string with the given parsers.
diff --git a/front_matter/test.ts b/front_matter/test.ts
index c445e54007dc..0439d0c0e2f0 100644
--- a/front_matter/test.ts
+++ b/front_matter/test.ts
@@ -5,7 +5,9 @@ import { EXTRACT_REGEXP_MAP } from "./_formats.ts";
 export type Format = "yaml" | "toml" | "json" | "unknown";
 
 /**
- * Tests if a string has valid front matter. Supports YAML, TOML and JSON.
+ * Tests if a string has valid front matter.
+ * Supports {@link https://yaml.org | YAML}, {@link https://toml.io | TOML} and
+ * {@link https://www.json.org/ | JSON}.
  *
  * @param str String to test.
  * @param formats A list of formats to test for. Defaults to all supported formats.

From 77b8aece6c062cfc606442a904e3297a9309b939 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 15:07:05 +0900
Subject: [PATCH 02/19] use @example and split examples into smaller pieces

---
 front_matter/create_extractor.ts | 71 +++++++++++++++++++++++++-------
 1 file changed, 56 insertions(+), 15 deletions(-)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index 7908c9c1e443..b604d303a58f 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -79,43 +79,84 @@ function recognize(str: string, formats?: Format[]): Format {
  * @param formats A descriptor containing Format-parser pairs to use for each format.
  * @returns A function that extracts front matter from a string with the given parsers.
  *
+ * @example
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
  * import { parse as parseYAML } from "@std/yaml/parse";
- * import { parse as parseTOML } from "@std/toml/parse";
- * const extractYAML = createExtractor({ yaml: parseYAML as Parser });
- * const extractTOML = createExtractor({ toml: parseTOML as Parser });
- * const extractJSON = createExtractor({ json: JSON.parse as Parser });
- * const extractYAMLOrJSON = createExtractor({
- *     yaml: parseYAML as Parser,
- *     json: JSON.parse as Parser,
- * });
  *
- * let { attrs, body, frontMatter } = extractYAML<{ title: string }>("---\ntitle: Three dashes marks the spot\n---\nferret");
+ * const extractYAML = createExtractor({ yaml: parseYAML as Parser });
+ * const { attrs, body, frontMatter } = extractYAML<{ title: string }>(
+ * `---
+ * title: Three dashes marks the spot
+ * ---
+ * ferret`);
  * assertEquals(attrs.title, "Three dashes marks the spot");
  * assertEquals(body, "ferret");
  * assertEquals(frontMatter, "title: Three dashes marks the spot");
+ * ```
  *
- * ({ attrs, body, frontMatter } = extractTOML<{ title: string }>("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n"));
+ * @example
+ * ```ts
+ * import { createExtractor, Parser } from "@std/front-matter";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ * import { parse as parseTOML } from "@std/toml/parse";
+ *
+ * const extractTOML = createExtractor({ toml: parseTOML as Parser });
+ * const { attrs, body, frontMatter } = extractTOML<{ title: string }>(
+ * `---toml
+ * title = 'Three dashes followed by format marks the spot'
+ * ---
+ * `);
  * assertEquals(attrs.title, "Three dashes followed by format marks the spot");
  * assertEquals(body, "");
  * assertEquals(frontMatter, "title = 'Three dashes followed by format marks the spot'");
+ * ```
  *
- * ({ attrs, body, frontMatter } = extractJSON<{ title: string }>("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\ngoat"));
+ * @example
+ * ```ts
+ * import { createExtractor, Parser } from "@std/front-matter";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const extractJSON = createExtractor({ json: JSON.parse as Parser });
+ * const { attrs, body, frontMatter } = extractJSON<{ title: string }>(
+ * `---json
+ * {"title": "Three dashes followed by format marks the spot"}
+ * ---
+ * goat`);
  * assertEquals(attrs.title, "Three dashes followed by format marks the spot");
  * assertEquals(body, "goat");
- * assertEquals(frontMatter, "{\"title\": \"Three dashes followed by format marks the spot\"}");
+ * assertEquals(frontMatter, `{"title": "Three dashes followed by format marks the spot"}`);
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { createExtractor, Parser } from "@std/front-matter";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ * import { parse as parseYAML } from "@std/yaml/parse";
+ *
+ * const extractYAMLOrJSON = createExtractor({
+ *   yaml: parseYAML as Parser,
+ *   json: JSON.parse as Parser,
+ * });
  *
- * ({ attrs, body, frontMatter } = extractYAMLOrJSON<{ title: string }>("---\ntitle: Three dashes marks the spot\n---\nferret"));
+ * let { attrs, body, frontMatter } = extractYAMLOrJSON<{ title: string }>(
+ * `---
+ * title: Three dashes marks the spot
+ * ---
+ * ferret`);
  * assertEquals(attrs.title, "Three dashes marks the spot");
  * assertEquals(body, "ferret");
  * assertEquals(frontMatter, "title: Three dashes marks the spot");
  *
- * ({ attrs, body, frontMatter } = extractYAMLOrJSON<{ title: string }>("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\ngoat"));
+ * ({ attrs, body, frontMatter } = extractYAMLOrJSON<{ title: string }>(
+ * `---json
+ * {"title": "Three dashes followed by format marks the spot"}
+ * ---
+ * goat`));
  * assertEquals(attrs.title, "Three dashes followed by format marks the spot");
  * assertEquals(body, "goat");
- * assertEquals(frontMatter, "{\"title\": \"Three dashes followed by format marks the spot\"}");
+ * assertEquals(frontMatter, `{"title": "Three dashes followed by format marks the spot"}`);
  * ```
  */
 export function createExtractor(

From 5bf8ed1c1fc97898c0527f3b78d33d5ef7bb086e Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 15:26:15 +0900
Subject: [PATCH 03/19] fix

---
 front_matter/test.ts | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/front_matter/test.ts b/front_matter/test.ts
index 0439d0c0e2f0..0ecc3ec15adf 100644
--- a/front_matter/test.ts
+++ b/front_matter/test.ts
@@ -12,13 +12,33 @@ export type Format = "yaml" | "toml" | "json" | "unknown";
  * @param str String to test.
  * @param formats A list of formats to test for. Defaults to all supported formats.
  *
+ * @example
  * ```ts
  * import { test } from "@std/front-matter/test";
  *
- * test("---\ntitle: Three dashes marks the spot\n---\n"); // true
- * test("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n"); // true
- * test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n"); // true
- * test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n", ["yaml"]); // false
+ * test(
+ * `---
+ * title: Three dashes marks the spot
+ * ---
+ * `); // true
+ *
+ * test(
+ * `---toml
+ * title = 'Three dashes followed by format marks the spot'
+ * ---
+ * `); // true
+ *
+ * test(
+ * `---json
+ * {"title": "Three dashes followed by format marks the spot"}
+ * ---
+ * `); // true
+ *
+ * test(
+ * `---json
+ * {"title": "Three dashes followed by format marks the spot"}
+ * ---
+ * `, ["yaml"]); // false
  * ```
  */
 export function test(

From 4fec4e460dd68a8992fc79ab01a3628df239a88b Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 15:30:58 +0900
Subject: [PATCH 04/19] add @example

---
 front_matter/create_extractor.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index b604d303a58f..cdb9c6e3bb95 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -40,6 +40,7 @@ function _extract<T>(
  * @param str String to recognize.
  * @param formats A list of formats to recognize. Defaults to all supported formats.
  *
+ * @example
  * ```ts
  * import { recognize } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
@@ -50,6 +51,7 @@ function _extract<T>(
  * assertEquals(recognize("---xml\n<title>Three dashes marks the spot</title>\n---\n"), "unknown");
  *
  * assertEquals(recognize("---json\n<title>Three dashes marks the spot</title>\n---\n", ["yaml"]), "unknown");
+ * ```
  */
 function recognize(str: string, formats?: Format[]): Format {
   if (!formats) {

From 4999c4f6cc56048be4bfaf317d262d589fa5d418 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 15:34:16 +0900
Subject: [PATCH 05/19] make Format type defined in test.ts a single source

---
 front_matter/create_extractor.ts | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index cdb9c6e3bb95..5c4d3195bb41 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -1,8 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
 import { EXTRACT_REGEXP_MAP, RECOGNIZE_REGEXP_MAP } from "./_formats.ts";
-
-type Format = "yaml" | "toml" | "json" | "unknown";
+import type { Format } from "./test.ts";
 
 /** Return type for {@linkcode Extractor}. */
 export type Extract<T> = {
@@ -162,7 +161,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * ```
  */
 export function createExtractor(
-  formats: Partial<Record<"yaml" | "toml" | "json" | "unknown", Parser>>,
+  formats: Partial<Record<Format, Parser>>,
 ): Extractor {
   const formatKeys = Object.keys(formats) as Format[];
 

From 67f88f5d01cfa6dd895b0f8f103fc9526c8a7da3 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 15:46:35 +0900
Subject: [PATCH 06/19] add doc comment for Format

---
 front_matter/test.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/front_matter/test.ts b/front_matter/test.ts
index 0ecc3ec15adf..dad451deaf3a 100644
--- a/front_matter/test.ts
+++ b/front_matter/test.ts
@@ -2,6 +2,7 @@
 
 import { EXTRACT_REGEXP_MAP } from "./_formats.ts";
 
+/** Supported format for front matter. `"unknown"` is used when auto format detection logic fails. */
 export type Format = "yaml" | "toml" | "json" | "unknown";
 
 /**

From cdba0642d55c9d6a38f6b0ff9b3627a9eb95fe85 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 15:55:38 +0900
Subject: [PATCH 07/19] use assert

---
 front_matter/test.ts | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/front_matter/test.ts b/front_matter/test.ts
index dad451deaf3a..77b996753410 100644
--- a/front_matter/test.ts
+++ b/front_matter/test.ts
@@ -16,30 +16,35 @@ export type Format = "yaml" | "toml" | "json" | "unknown";
  * @example
  * ```ts
  * import { test } from "@std/front-matter/test";
+ * import { assert } from "@std/assert/assert";
  *
- * test(
+ * const yamlValid = test(
  * `---
  * title: Three dashes marks the spot
  * ---
- * `); // true
+ * `);
+ * assert(yamlValid);
  *
- * test(
+ * const tomlValid = test(
  * `---toml
  * title = 'Three dashes followed by format marks the spot'
  * ---
- * `); // true
+ * `);
+ * assert(tomlValid);
  *
- * test(
+ * const jsonValid = test(
  * `---json
  * {"title": "Three dashes followed by format marks the spot"}
  * ---
- * `); // true
+ * `);
+ * assert(jsonValid);
  *
- * test(
+ * const parseJsonFrontMatterWithYamlFormat = test(
  * `---json
  * {"title": "Three dashes followed by format marks the spot"}
  * ---
- * `, ["yaml"]); // false
+ * `, ["yaml"]);
+ * assert(!parseJsonFrontMatterWithYamlFormat);
  * ```
  */
 export function test(

From 245370cc6164db56686e47454a697298ff0f39c1 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 15:58:33 +0900
Subject: [PATCH 08/19] add front_matter/mod.ts to entrypoints and lint target

---
 _tools/check_docs.ts | 1 +
 deno.json            | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts
index 92a5faa095f3..26bd09cd1fea 100644
--- a/_tools/check_docs.ts
+++ b/_tools/check_docs.ts
@@ -21,6 +21,7 @@ const ENTRY_POINTS = [
   "../bytes/mod.ts",
   "../datetime/mod.ts",
   "../collections/mod.ts",
+  "../front_matter/mod.ts",
   "../internal/mod.ts",
   "../media_types/mod.ts",
 ] as const;
diff --git a/deno.json b/deno.json
index 9e1f9cc5206b..95b3b8f56e2d 100644
--- a/deno.json
+++ b/deno.json
@@ -19,7 +19,7 @@
     "lint:circular": "deno run --allow-env --allow-read --allow-net=deno.land,jsr.io ./_tools/check_circular_package_dependencies.ts",
     "lint:mod-exports": "deno run --allow-env --allow-read ./_tools/check_mod_exports.ts",
     "lint:tools-types": "deno check _tools/*.ts",
-    "lint:docs": "deno run -A _tools/check_docs.ts && deno doc --lint collections/mod.ts bytes/mod.ts datetime/mod.ts internal/mod.ts media_types/mod.ts url/mod.ts",
+    "lint:docs": "deno run -A _tools/check_docs.ts && deno doc --lint collections/mod.ts bytes/mod.ts datetime/mod.ts front_matter/mod.ts internal/mod.ts media_types/mod.ts url/mod.ts",
     "lint": "deno lint && deno task fmt:licence-headers --check && deno task lint:circular && deno task lint:deprecations && deno task lint:tools-types && deno task lint:mod-exports && deno task lint:docs",
     "typos": "typos -c ./.github/workflows/typos.toml",
     "build:crypto": "deno task --cwd crypto/_wasm wasmbuild",

From 207c09aaf84f61af509a09c851895fda7284e10a Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 16:03:09 +0900
Subject: [PATCH 09/19] add @returns

---
 front_matter/test.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/front_matter/test.ts b/front_matter/test.ts
index 77b996753410..8b7abf5c55b2 100644
--- a/front_matter/test.ts
+++ b/front_matter/test.ts
@@ -12,6 +12,7 @@ export type Format = "yaml" | "toml" | "json" | "unknown";
  *
  * @param str String to test.
  * @param formats A list of formats to test for. Defaults to all supported formats.
+ * @returns `true` if the string has valid front matter, otherwise `false`.
  *
  * @example
  * ```ts

From 4fe2448688515458986f0df4c68476a1044c1f10 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Tue, 21 May 2024 16:11:07 +0900
Subject: [PATCH 10/19] remove doc comment from private function

---
 front_matter/create_extractor.ts | 19 -------------------
 1 file changed, 19 deletions(-)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index 5c4d3195bb41..b584a6957036 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -33,25 +33,6 @@ function _extract<T>(
   return { frontMatter, body, attrs };
 }
 
-/**
- * Recognizes the format of the front matter in a string. Supports YAML, TOML and JSON.
- *
- * @param str String to recognize.
- * @param formats A list of formats to recognize. Defaults to all supported formats.
- *
- * @example
- * ```ts
- * import { recognize } from "@std/front-matter";
- * import { assertEquals } from "@std/assert/assert-equals";
- *
- * assertEquals(recognize("---\ntitle: Three dashes marks the spot\n---\n"), "yaml");
- * assertEquals(recognize("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n"), "toml");
- * assertEquals(recognize("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n"), "json");
- * assertEquals(recognize("---xml\n<title>Three dashes marks the spot</title>\n---\n"), "unknown");
- *
- * assertEquals(recognize("---json\n<title>Three dashes marks the spot</title>\n---\n", ["yaml"]), "unknown");
- * ```
- */
 function recognize(str: string, formats?: Format[]): Format {
   if (!formats) {
     formats = Object.keys(RECOGNIZE_REGEXP_MAP) as Format[];

From 2668c7c9f546966416e79141a15b5703cc705f60 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Fri, 24 May 2024 21:47:04 +0900
Subject: [PATCH 11/19] move Format type to _types.ts

---
 front_matter/_types.ts           | 4 ++++
 front_matter/create_extractor.ts | 2 +-
 front_matter/test.ts             | 4 ++--
 3 files changed, 7 insertions(+), 3 deletions(-)
 create mode 100644 front_matter/_types.ts

diff --git a/front_matter/_types.ts b/front_matter/_types.ts
new file mode 100644
index 000000000000..8acb5fd3fa6b
--- /dev/null
+++ b/front_matter/_types.ts
@@ -0,0 +1,4 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+/** Supported format for front matter. `"unknown"` is used when auto format detection logic fails. */
+export type Format = "yaml" | "toml" | "json" | "unknown";
diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index b584a6957036..2e2386826ac5 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -1,7 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
 import { EXTRACT_REGEXP_MAP, RECOGNIZE_REGEXP_MAP } from "./_formats.ts";
-import type { Format } from "./test.ts";
+import type { Format } from "./_types.ts";
 
 /** Return type for {@linkcode Extractor}. */
 export type Extract<T> = {
diff --git a/front_matter/test.ts b/front_matter/test.ts
index 8b7abf5c55b2..d03ef93abc1f 100644
--- a/front_matter/test.ts
+++ b/front_matter/test.ts
@@ -1,9 +1,9 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
 import { EXTRACT_REGEXP_MAP } from "./_formats.ts";
+import type { Format } from "./_types.ts";
 
-/** Supported format for front matter. `"unknown"` is used when auto format detection logic fails. */
-export type Format = "yaml" | "toml" | "json" | "unknown";
+export type { Format };
 
 /**
  * Tests if a string has valid front matter.

From 7c98abe17f83cf9341f3db9c6c27fd1f7320b828 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Fri, 24 May 2024 22:07:53 +0900
Subject: [PATCH 12/19] give titles to examples

---
 front_matter/create_extractor.ts |  8 ++++----
 front_matter/test.ts             | 22 ++++++++++++++++++++--
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index 2e2386826ac5..fb01424084a1 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -61,7 +61,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * @param formats A descriptor containing Format-parser pairs to use for each format.
  * @returns A function that extracts front matter from a string with the given parsers.
  *
- * @example
+ * @example Parse YAML front matter
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
@@ -78,7 +78,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * assertEquals(frontMatter, "title: Three dashes marks the spot");
  * ```
  *
- * @example
+ * @example Parse TOML front matter
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
@@ -95,7 +95,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * assertEquals(frontMatter, "title = 'Three dashes followed by format marks the spot'");
  * ```
  *
- * @example
+ * @example Parse JSON front matter
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
@@ -111,7 +111,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * assertEquals(frontMatter, `{"title": "Three dashes followed by format marks the spot"}`);
  * ```
  *
- * @example
+ * @example Parse YAML or JSON front matter
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
diff --git a/front_matter/test.ts b/front_matter/test.ts
index d03ef93abc1f..9e60a6b5e681 100644
--- a/front_matter/test.ts
+++ b/front_matter/test.ts
@@ -14,7 +14,7 @@ export type { Format };
  * @param formats A list of formats to test for. Defaults to all supported formats.
  * @returns `true` if the string has valid front matter, otherwise `false`.
  *
- * @example
+ * @example Test for valid YAML front matter
  * ```ts
  * import { test } from "@std/front-matter/test";
  * import { assert } from "@std/assert/assert";
@@ -25,6 +25,12 @@ export type { Format };
  * ---
  * `);
  * assert(yamlValid);
+ * ```
+ *
+ * @example Test for valid TOML front matter
+ * ```ts
+ * import { test } from "@std/front-matter/test";
+ * import { assert } from "@std/assert/assert";
  *
  * const tomlValid = test(
  * `---toml
@@ -32,6 +38,12 @@ export type { Format };
  * ---
  * `);
  * assert(tomlValid);
+ * ```
+ *
+ * @example Test for valid JSON front matter
+ * ```ts
+ * import { test } from "@std/front-matter/test";
+ * import { assert } from "@std/assert/assert";
  *
  * const jsonValid = test(
  * `---json
@@ -39,13 +51,19 @@ export type { Format };
  * ---
  * `);
  * assert(jsonValid);
+ * ```
+ *
+ * @example JSON front matter is not valid as YAML
+ * ```ts
+ * import { test } from "@std/front-matter/test";
+ * import { assertFalse } from "@std/assert/assert-false";
  *
  * const parseJsonFrontMatterWithYamlFormat = test(
  * `---json
  * {"title": "Three dashes followed by format marks the spot"}
  * ---
  * `, ["yaml"]);
- * assert(!parseJsonFrontMatterWithYamlFormat);
+ * assertFalse(parseJsonFrontMatterWithYamlFormat);
  * ```
  */
 export function test(

From ab1ab203dfbea73fd6541cfdd6942cc3433aab55 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Fri, 24 May 2024 22:36:06 +0900
Subject: [PATCH 13/19] camelcase

---
 front_matter/_test_utils.ts           | 10 ++---
 front_matter/any.ts                   |  8 ++--
 front_matter/any_test.ts              | 16 ++++----
 front_matter/create_extractor.ts      | 26 ++++++-------
 front_matter/create_extractor_test.ts | 54 +++++++++++++--------------
 front_matter/json_test.ts             |  4 +-
 front_matter/toml_test.ts             |  8 ++--
 front_matter/yaml_test.ts             |  8 ++--
 8 files changed, 67 insertions(+), 67 deletions(-)

diff --git a/front_matter/_test_utils.ts b/front_matter/_test_utils.ts
index 15bf649e3660..82e15db67eba 100644
--- a/front_matter/_test_utils.ts
+++ b/front_matter/_test_utils.ts
@@ -77,7 +77,7 @@ export function runExtractTypeErrorTests(
   });
 }
 
-export async function runExtractJSONTests(
+export async function runExtractJsonTests(
   extractFn: ExtractFn,
 ) {
   const str = await Deno.readTextFile(resolveTestDataPath("json.md"));
@@ -110,7 +110,7 @@ export async function runExtractJSONTests(
   );
 }
 
-export async function runExtractYAMLTests1(
+export async function runExtractYamlTests1(
   extractFn: ExtractFn,
 ) {
   const str = await Deno.readTextFile(resolveTestDataPath("yaml1.md"));
@@ -138,7 +138,7 @@ expanded-description: with some --- crazy stuff in it`,
   );
 }
 
-export async function runExtractYAMLTests2(
+export async function runExtractYamlTests2(
   extractFn: ExtractFn,
 ) {
   const str = await Deno.readTextFile(resolveTestDataPath("yaml2.md"));
@@ -166,7 +166,7 @@ expanded-description: with some --- crazy stuff in it`,
   );
 }
 
-export async function runExtractTOMLTests(
+export async function runExtractTomlTests(
   extractFn: ExtractFn,
 ) {
   const str = await Deno.readTextFile(resolveTestDataPath("toml.md"));
@@ -194,7 +194,7 @@ tags = ['toml', 'front-matter']
   );
 }
 
-export async function runExtractTOMLTests2(
+export async function runExtractTomlTests2(
   extractFn: ExtractFn,
 ) {
   const str = await Deno.readTextFile(resolveTestDataPath("toml2.md"));
diff --git a/front_matter/any.ts b/front_matter/any.ts
index f98ef1ae9d1c..e169f5d74287 100644
--- a/front_matter/any.ts
+++ b/front_matter/any.ts
@@ -5,8 +5,8 @@ import {
   type Extractor,
   type Parser,
 } from "./create_extractor.ts";
-import { parse as parseYAML } from "@std/yaml/parse";
-import { parse as parseTOML } from "@std/toml/parse";
+import { parse as parseYaml } from "@std/yaml/parse";
+import { parse as parseToml } from "@std/toml/parse";
 
 /**
  * Extracts and parses {@link https://yaml.org | YAML}, {@link https://toml.io |
@@ -31,7 +31,7 @@ import { parse as parseTOML } from "@std/toml/parse";
  * ```
  */
 export const extract: Extractor = createExtractor({
-  yaml: parseYAML as Parser,
-  toml: parseTOML as Parser,
+  yaml: parseYaml as Parser,
+  toml: parseToml as Parser,
   json: JSON.parse as Parser,
 });
diff --git a/front_matter/any_test.ts b/front_matter/any_test.ts
index 090498c7d9f7..7fe1ee3ebc69 100644
--- a/front_matter/any_test.ts
+++ b/front_matter/any_test.ts
@@ -3,11 +3,11 @@
 import { test } from "./test.ts";
 import { extract } from "./any.ts";
 import {
-  runExtractJSONTests,
-  runExtractTOMLTests,
+  runExtractJsonTests,
+  runExtractTomlTests,
   runExtractTypeErrorTests,
-  runExtractYAMLTests1,
-  runExtractYAMLTests2,
+  runExtractYamlTests1,
+  runExtractYamlTests2,
   runTestInvalidInputTests,
   runTestValidInputTests,
 } from "./_test_utils.ts";
@@ -27,11 +27,11 @@ Deno.test("extract() extracts type error on invalid input", () => {
 });
 
 Deno.test("extract() parses yaml delineate by `---`", async () => {
-  await runExtractYAMLTests1(extract);
+  await runExtractYamlTests1(extract);
 });
 
 Deno.test("extract() parses yaml delineate by `---yaml`", async () => {
-  await runExtractYAMLTests2(extract);
+  await runExtractYamlTests2(extract);
 });
 
 // JSON //
@@ -49,7 +49,7 @@ Deno.test("extract() extracts type error on invalid json input", () => {
 });
 
 Deno.test("extract() parses json delineate by ---json", async () => {
-  await runExtractJSONTests(extract);
+  await runExtractJsonTests(extract);
 });
 
 // TOML //
@@ -67,5 +67,5 @@ Deno.test("extract() extracts type error on invalid toml input", () => {
 });
 
 Deno.test("extract() parses toml delineate by ---toml", async () => {
-  await runExtractTOMLTests(extract);
+  await runExtractTomlTests(extract);
 });
diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index fb01424084a1..02dd38fe83f8 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -65,10 +65,10 @@ function recognize(str: string, formats?: Format[]): Format {
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
- * import { parse as parseYAML } from "@std/yaml/parse";
+ * import { parse as parseYaml } from "@std/yaml/parse";
  *
- * const extractYAML = createExtractor({ yaml: parseYAML as Parser });
- * const { attrs, body, frontMatter } = extractYAML<{ title: string }>(
+ * const extractYaml = createExtractor({ yaml: parseYaml as Parser });
+ * const { attrs, body, frontMatter } = extractYaml<{ title: string }>(
  * `---
  * title: Three dashes marks the spot
  * ---
@@ -82,10 +82,10 @@ function recognize(str: string, formats?: Format[]): Format {
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
- * import { parse as parseTOML } from "@std/toml/parse";
+ * import { parse as parseToml } from "@std/toml/parse";
  *
- * const extractTOML = createExtractor({ toml: parseTOML as Parser });
- * const { attrs, body, frontMatter } = extractTOML<{ title: string }>(
+ * const extractToml = createExtractor({ toml: parseToml as Parser });
+ * const { attrs, body, frontMatter } = extractToml<{ title: string }>(
  * `---toml
  * title = 'Three dashes followed by format marks the spot'
  * ---
@@ -100,8 +100,8 @@ function recognize(str: string, formats?: Format[]): Format {
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
  *
- * const extractJSON = createExtractor({ json: JSON.parse as Parser });
- * const { attrs, body, frontMatter } = extractJSON<{ title: string }>(
+ * const extractJson = createExtractor({ json: JSON.parse as Parser });
+ * const { attrs, body, frontMatter } = extractJson<{ title: string }>(
  * `---json
  * {"title": "Three dashes followed by format marks the spot"}
  * ---
@@ -115,14 +115,14 @@ function recognize(str: string, formats?: Format[]): Format {
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
- * import { parse as parseYAML } from "@std/yaml/parse";
+ * import { parse as parseYaml } from "@std/yaml/parse";
  *
- * const extractYAMLOrJSON = createExtractor({
- *   yaml: parseYAML as Parser,
+ * const extractYamlOrJson = createExtractor({
+ *   yaml: parseYaml as Parser,
  *   json: JSON.parse as Parser,
  * });
  *
- * let { attrs, body, frontMatter } = extractYAMLOrJSON<{ title: string }>(
+ * let { attrs, body, frontMatter } = extractYamlOrJson<{ title: string }>(
  * `---
  * title: Three dashes marks the spot
  * ---
@@ -131,7 +131,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * assertEquals(body, "ferret");
  * assertEquals(frontMatter, "title: Three dashes marks the spot");
  *
- * ({ attrs, body, frontMatter } = extractYAMLOrJSON<{ title: string }>(
+ * ({ attrs, body, frontMatter } = extractYamlOrJson<{ title: string }>(
  * `---json
  * {"title": "Three dashes followed by format marks the spot"}
  * ---
diff --git a/front_matter/create_extractor_test.ts b/front_matter/create_extractor_test.ts
index d3000e7453f8..1a3b0df0c822 100644
--- a/front_matter/create_extractor_test.ts
+++ b/front_matter/create_extractor_test.ts
@@ -1,43 +1,43 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
 import { assertThrows } from "@std/assert";
-import { parse as parseYAML } from "@std/yaml/parse";
-import { parse as parseTOML } from "@std/toml/parse";
+import { parse as parseYaml } from "@std/yaml/parse";
+import { parse as parseToml } from "@std/toml/parse";
 import {
   resolveTestDataPath,
-  runExtractJSONTests,
-  runExtractTOMLTests,
+  runExtractJsonTests,
+  runExtractTomlTests,
   runExtractTypeErrorTests,
-  runExtractYAMLTests1,
-  runExtractYAMLTests2,
+  runExtractYamlTests1,
+  runExtractYamlTests2,
 } from "./_test_utils.ts";
 import { createExtractor, type Parser } from "./create_extractor.ts";
 
-const extractYAML = createExtractor({ "yaml": parseYAML as Parser });
-const extractTOML = createExtractor({ "toml": parseTOML as Parser });
-const extractJSON = createExtractor({ "json": JSON.parse as Parser });
-const extractYAMLOrJSON = createExtractor({
-  "yaml": parseYAML as Parser,
+const extractYaml = createExtractor({ "yaml": parseYaml as Parser });
+const extractToml = createExtractor({ "toml": parseToml as Parser });
+const extractJson = createExtractor({ "json": JSON.parse as Parser });
+const extractYamlOrJson = createExtractor({
+  "yaml": parseYaml as Parser,
   "json": JSON.parse as Parser,
 });
 const extractAny = createExtractor({
-  "yaml": parseYAML as Parser,
+  "yaml": parseYaml as Parser,
   "json": JSON.parse as Parser,
-  "toml": parseTOML as Parser,
+  "toml": parseToml as Parser,
 });
 
 // YAML //
 
 Deno.test("createExtractor() extracts yaml type error on invalid input", () => {
-  runExtractTypeErrorTests("yaml", extractYAML);
+  runExtractTypeErrorTests("yaml", extractYaml);
 });
 
 Deno.test("createExtractor() parses yaml delineate by `---`", async () => {
-  await runExtractYAMLTests1(extractYAML);
+  await runExtractYamlTests1(extractYaml);
 });
 
 Deno.test("createExtractor() parses yaml delineate by `---yaml`", async () => {
-  await runExtractYAMLTests2(extractYAML);
+  await runExtractYamlTests2(extractYaml);
 });
 
 Deno.test({
@@ -61,34 +61,34 @@ Deno.test({
 // JSON //
 
 Deno.test("createExtractor() extracts json type error on invalid input", () => {
-  runExtractTypeErrorTests("json", extractJSON);
+  runExtractTypeErrorTests("json", extractJson);
 });
 
 Deno.test("createExtractor() parses json delineate by ---json", async () => {
-  await runExtractJSONTests(extractJSON);
+  await runExtractJsonTests(extractJson);
 });
 
 // TOML //
 
 Deno.test("createExtractor() extracts toml type error on invalid input", () => {
-  runExtractTypeErrorTests("toml", extractTOML);
+  runExtractTypeErrorTests("toml", extractToml);
 });
 
 Deno.test("createExtractor() parses toml delineate by ---toml", async () => {
-  await runExtractTOMLTests(extractTOML);
+  await runExtractTomlTests(extractToml);
 });
 
 // MULTIPLE FORMATS //
 
 Deno.test("createExtractor() parses yaml or json input", async () => {
-  await runExtractYAMLTests1(extractYAMLOrJSON);
-  await runExtractYAMLTests2(extractYAMLOrJSON);
-  await runExtractJSONTests(extractYAMLOrJSON);
+  await runExtractYamlTests1(extractYamlOrJson);
+  await runExtractYamlTests2(extractYamlOrJson);
+  await runExtractJsonTests(extractYamlOrJson);
 });
 
 Deno.test("createExtractor() parses any input", async () => {
-  await runExtractYAMLTests1(extractAny);
-  await runExtractYAMLTests2(extractAny);
-  await runExtractJSONTests(extractAny);
-  await runExtractTOMLTests(extractAny);
+  await runExtractYamlTests1(extractAny);
+  await runExtractYamlTests2(extractAny);
+  await runExtractJsonTests(extractAny);
+  await runExtractTomlTests(extractAny);
 });
diff --git a/front_matter/json_test.ts b/front_matter/json_test.ts
index 23966466b95b..b7cf48af43d0 100644
--- a/front_matter/json_test.ts
+++ b/front_matter/json_test.ts
@@ -3,7 +3,7 @@
 import { test } from "./test.ts";
 import { extract } from "./json.ts";
 import {
-  runExtractJSONTests,
+  runExtractJsonTests,
   runExtractTypeErrorTests,
   runTestInvalidInputTests,
   runTestValidInputTests,
@@ -22,5 +22,5 @@ Deno.test("json() extracts type error on invalid input", () => {
 });
 
 Deno.test("json() parses json delineate by ---json", async () => {
-  await runExtractJSONTests(extract);
+  await runExtractJsonTests(extract);
 });
diff --git a/front_matter/toml_test.ts b/front_matter/toml_test.ts
index 231730e62d6e..196f34d1e963 100644
--- a/front_matter/toml_test.ts
+++ b/front_matter/toml_test.ts
@@ -3,8 +3,8 @@
 import { test } from "./test.ts";
 import { extract } from "./toml.ts";
 import {
-  runExtractTOMLTests,
-  runExtractTOMLTests2,
+  runExtractTomlTests,
+  runExtractTomlTests2,
   runExtractTypeErrorTests,
   runTestInvalidInputTests,
   runTestValidInputTests,
@@ -23,9 +23,9 @@ Deno.test("toml() extracts type error on invalid input", () => {
 });
 
 Deno.test("toml() parses toml delineate by ---toml", async () => {
-  await runExtractTOMLTests(extract);
+  await runExtractTomlTests(extract);
 });
 
 Deno.test("toml() parses toml delineate by +++", async () => {
-  await runExtractTOMLTests2(extract);
+  await runExtractTomlTests2(extract);
 });
diff --git a/front_matter/yaml_test.ts b/front_matter/yaml_test.ts
index b78cbbde280a..7128fa675e19 100644
--- a/front_matter/yaml_test.ts
+++ b/front_matter/yaml_test.ts
@@ -4,8 +4,8 @@ import { test } from "./test.ts";
 import { extract } from "./yaml.ts";
 import {
   runExtractTypeErrorTests,
-  runExtractYAMLTests1,
-  runExtractYAMLTests2,
+  runExtractYamlTests1,
+  runExtractYamlTests2,
   runTestInvalidInputTests,
   runTestValidInputTests,
 } from "./_test_utils.ts";
@@ -23,9 +23,9 @@ Deno.test("yaml() extracts type error on invalid input", () => {
 });
 
 Deno.test("yaml() parses yaml delineate by `---`", async () => {
-  await runExtractYAMLTests1(extract);
+  await runExtractYamlTests1(extract);
 });
 
 Deno.test("yaml() parses yaml delineate by `---yaml`", async () => {
-  await runExtractYAMLTests2(extract);
+  await runExtractYamlTests2(extract);
 });

From 7d04c69660b37eb045b44f7957055b11cb274b27 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Fri, 24 May 2024 22:51:55 +0900
Subject: [PATCH 14/19] export pre-built extract functions from module root

---
 front_matter/create_extractor.ts | 7 +++++++
 front_matter/mod.ts              | 8 +++++---
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index 02dd38fe83f8..0583d7dba355 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -58,6 +58,13 @@ function recognize(str: string, formats?: Format[]): Format {
  * Supports {@link https://yaml.org | YAML}, {@link https://toml.io | TOML} and
  * {@link https://www.json.org/ | JSON}.
  *
+ * For simple use cases where you know which format to parse in advance, use the
+ * pre-built extractors:
+ *
+ * - {@linkcode extractYaml}
+ * - {@linkcode extractToml}
+ * - {@linkcode extractJson}
+ *
  * @param formats A descriptor containing Format-parser pairs to use for each format.
  * @returns A function that extracts front matter from a string with the given parsers.
  *
diff --git a/front_matter/mod.ts b/front_matter/mod.ts
index f075478b3112..d639b1230c5c 100644
--- a/front_matter/mod.ts
+++ b/front_matter/mod.ts
@@ -115,9 +115,11 @@
  *
  * @module
  */
-import type { extract as extractJson } from "./json.ts";
-import type { extract as extractToml } from "./toml.ts";
-import type { extract as extractYaml } from "./yaml.ts";
+import { extract as extractJson } from "./json.ts";
+import { extract as extractToml } from "./toml.ts";
+import { extract as extractYaml } from "./yaml.ts";
 
 export * from "./create_extractor.ts";
 export * from "./test.ts";
+
+export { extractJson, extractToml, extractYaml };

From c4241ca15a6ab0577d38a3c1234c7afa17d9e886 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Fri, 24 May 2024 23:07:03 +0900
Subject: [PATCH 15/19] remove unused lint ignore directive

---
 front_matter/mod.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/front_matter/mod.ts b/front_matter/mod.ts
index d639b1230c5c..278cd05b3b6c 100644
--- a/front_matter/mod.ts
+++ b/front_matter/mod.ts
@@ -1,4 +1,3 @@
-// deno-lint-ignore-file no-unused-vars
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // Copyright (c) Jason Campbell. MIT license
 

From 9c48b3c215b596aca0c2fa4c687b35db4511c0e2 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Fri, 24 May 2024 23:15:17 +0900
Subject: [PATCH 16/19] fix examples

---
 front_matter/create_extractor.ts |  8 ++++----
 front_matter/json.ts             | 11 +++++++----
 front_matter/toml.ts             | 11 +++++++----
 front_matter/yaml.ts             | 11 +++++++----
 4 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index 0583d7dba355..99d42c3fc793 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -68,7 +68,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * @param formats A descriptor containing Format-parser pairs to use for each format.
  * @returns A function that extracts front matter from a string with the given parsers.
  *
- * @example Parse YAML front matter
+ * @example Extract YAML front matter
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
@@ -85,7 +85,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * assertEquals(frontMatter, "title: Three dashes marks the spot");
  * ```
  *
- * @example Parse TOML front matter
+ * @example Extract TOML front matter
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
@@ -102,7 +102,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * assertEquals(frontMatter, "title = 'Three dashes followed by format marks the spot'");
  * ```
  *
- * @example Parse JSON front matter
+ * @example Extract JSON front matter
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
@@ -118,7 +118,7 @@ function recognize(str: string, formats?: Format[]): Format {
  * assertEquals(frontMatter, `{"title": "Three dashes followed by format marks the spot"}`);
  * ```
  *
- * @example Parse YAML or JSON front matter
+ * @example Extract YAML or JSON front matter
  * ```ts
  * import { createExtractor, Parser } from "@std/front-matter";
  * import { assertEquals } from "@std/assert/assert-equals";
diff --git a/front_matter/json.ts b/front_matter/json.ts
index c841918ea689..8e3630421e1d 100644
--- a/front_matter/json.ts
+++ b/front_matter/json.ts
@@ -10,9 +10,10 @@ import {
  * Extracts and parses {@link https://www.json.org/ | JSON } from the metadata
  * of front matter content.
  *
- * @example
+ * @example Extract JSON front matter
  * ```ts
  * import { extract } from "@std/front-matter/json";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const output = `---json
  * {
@@ -22,9 +23,11 @@ import {
  * Hello, world!`;
  * const result = extract(output);
  *
- * result.frontMatter; // '{\n "title": "Three dashes marks the spot"\n}'
- * result.body; // "Hello, world!"
- * result.attrs; // { title: "Three dashes marks the spot" }
+ * assertEquals(result, {
+ *   frontMatter: '{\n  "title": "Three dashes marks the spot"\n}',
+ *   body: "Hello, world!",
+ *   attrs: { title: "Three dashes marks the spot" },
+ * });
  * ```
  */
 export const extract: Extractor = createExtractor({
diff --git a/front_matter/toml.ts b/front_matter/toml.ts
index eacd7393721d..a2a4f9dcf08b 100644
--- a/front_matter/toml.ts
+++ b/front_matter/toml.ts
@@ -11,9 +11,10 @@ import { parse } from "@std/toml/parse";
  * Extracts and parses {@link https://toml.io | TOML} from the metadata of
  * front matter content.
  *
- * @example
+ * @example Extract TOML front matter
  * ```ts
  * import { extract } from "@std/front-matter/toml";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const output = `---toml
  * title = "Three dashes marks the spot"
@@ -21,9 +22,11 @@ import { parse } from "@std/toml/parse";
  * Hello, world!`;
  * const result = extract(output);
  *
- * result.frontMatter; // 'title = "Three dashes marks the spot"'
- * result.body; // "Hello, world!"
- * result.attrs; // { title: "Three dashes marks the spot" }
+ * assertEquals(result, {
+ *   frontMatter: 'title = "Three dashes marks the spot"',
+ *   body: "Hello, world!",
+ *   attrs: { title: "Three dashes marks the spot" },
+ * });
  * ```
  */
 export const extract: Extractor = createExtractor({
diff --git a/front_matter/yaml.ts b/front_matter/yaml.ts
index 0fd02564ac12..95b2e295ed61 100644
--- a/front_matter/yaml.ts
+++ b/front_matter/yaml.ts
@@ -11,9 +11,10 @@ import { parse } from "@std/yaml/parse";
  * Extracts and parses {@link https://yaml.org | YAML} from the metadata of
  * front matter content.
  *
- * @example
+ * @example Extract YAML front matter
  * ```ts
  * import { extract } from "@std/front-matter/yaml";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const output = `---yaml
  * title: Three dashes marks the spot
@@ -21,9 +22,11 @@ import { parse } from "@std/yaml/parse";
  * Hello, world!`;
  * const result = extract(output);
  *
- * result.frontMatter; // 'title: Three dashes marks the spot'
- * result.body; // "Hello, world!"
- * result.attrs; // { title: "Three dashes marks the spot" }
+ * assertEquals(result, {
+ *   frontMatter: "title: Three dashes marks the spot",
+ *   body: "Hello, world!",
+ *   attrs: { title: "Three dashes marks the spot" },
+ * });
  * ```
  */
 export const extract: Extractor = createExtractor({

From 7997bc85a3e92b0881782458f849e763bd1859d9 Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Fri, 24 May 2024 23:23:12 +0900
Subject: [PATCH 17/19] bring back recognize doc

---
 front_matter/create_extractor.ts | 48 ++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index 99d42c3fc793..244c8e6be5db 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -33,6 +33,54 @@ function _extract<T>(
   return { frontMatter, body, attrs };
 }
 
+/**
+ * Recognizes the format of the front matter in a string.
+ * Supports {@link https://yaml.org | YAML}, {@link https://toml.io | TOML} and
+ * {@link https://www.json.org/ | JSON}.
+ *
+ * @param str String to recognize.
+ * @param formats A list of formats to recognize. Defaults to all supported formats.
+ *
+ * @example YAML
+ * ```ts
+ * import { recognize } from "@std/front-matter";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * assertEquals(recognize("---\ntitle: Three dashes marks the spot\n---\n"), "yaml");
+ * ```
+ *
+ * @example TOML
+ * ```ts
+ * import { recognize } from "@std/front-matter";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * assertEquals(recognize("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n"), "toml");
+ * ```
+ *
+ * @example JSON
+ * ```ts
+ * import { recognize } from "@std/front-matter";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * assertEquals(recognize("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n"), "json");
+ * ```
+ *
+ * @example XML (unsupported)
+ * ```ts
+ * import { recognize } from "@std/front-matter";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * assertEquals(recognize("---xml\n<title>Three dashes marks the spot</title>\n---\n"), "unknown");
+ * ```
+ *
+ * @example JSON front matter is not recognized by YAML parser
+ * ```ts
+ * import { recognize } from "@std/front-matter";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * assertEquals(recognize("---json\n<title>Three dashes marks the spot</title>\n---\n", ["yaml"]), "unknown");
+ * ```
+ */
 function recognize(str: string, formats?: Format[]): Format {
   if (!formats) {
     formats = Object.keys(RECOGNIZE_REGEXP_MAP) as Format[];

From e390fbed2deb43f1cb34d93695156f691e11d3ab Mon Sep 17 00:00:00 2001
From: Yusuke Tanaka <wing0920@gmail.com>
Date: Fri, 24 May 2024 23:28:48 +0900
Subject: [PATCH 18/19] remove example snippets as we cannot import private
 items

---
 front_matter/create_extractor.ts | 40 --------------------------------
 1 file changed, 40 deletions(-)

diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index 244c8e6be5db..d60c7eaca2cb 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -40,46 +40,6 @@ function _extract<T>(
  *
  * @param str String to recognize.
  * @param formats A list of formats to recognize. Defaults to all supported formats.
- *
- * @example YAML
- * ```ts
- * import { recognize } from "@std/front-matter";
- * import { assertEquals } from "@std/assert/assert-equals";
- *
- * assertEquals(recognize("---\ntitle: Three dashes marks the spot\n---\n"), "yaml");
- * ```
- *
- * @example TOML
- * ```ts
- * import { recognize } from "@std/front-matter";
- * import { assertEquals } from "@std/assert/assert-equals";
- *
- * assertEquals(recognize("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n"), "toml");
- * ```
- *
- * @example JSON
- * ```ts
- * import { recognize } from "@std/front-matter";
- * import { assertEquals } from "@std/assert/assert-equals";
- *
- * assertEquals(recognize("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n"), "json");
- * ```
- *
- * @example XML (unsupported)
- * ```ts
- * import { recognize } from "@std/front-matter";
- * import { assertEquals } from "@std/assert/assert-equals";
- *
- * assertEquals(recognize("---xml\n<title>Three dashes marks the spot</title>\n---\n"), "unknown");
- * ```
- *
- * @example JSON front matter is not recognized by YAML parser
- * ```ts
- * import { recognize } from "@std/front-matter";
- * import { assertEquals } from "@std/assert/assert-equals";
- *
- * assertEquals(recognize("---json\n<title>Three dashes marks the spot</title>\n---\n", ["yaml"]), "unknown");
- * ```
  */
 function recognize(str: string, formats?: Format[]): Format {
   if (!formats) {

From 0d793f6935f4102e6bad577ff9e6b0fcc0583059 Mon Sep 17 00:00:00 2001
From: Asher Gomez <ashersaupingomez@gmail.com>
Date: Mon, 27 May 2024 12:27:21 +1000
Subject: [PATCH 19/19] work

---
 front_matter/_types.ts           |  5 ++++-
 front_matter/create_extractor.ts | 12 ++++++------
 front_matter/mod.ts              |  9 ++++++---
 front_matter/test.ts             | 16 ++++++++--------
 4 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/front_matter/_types.ts b/front_matter/_types.ts
index 8acb5fd3fa6b..ddaa2cf9c848 100644
--- a/front_matter/_types.ts
+++ b/front_matter/_types.ts
@@ -1,4 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
-/** Supported format for front matter. `"unknown"` is used when auto format detection logic fails. */
+/**
+ * Supported format for front matter. `"unknown"` is used when auto format
+ * detection logic fails.
+ */
 export type Format = "yaml" | "toml" | "json" | "unknown";
diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts
index d60c7eaca2cb..f6352288f944 100644
--- a/front_matter/create_extractor.ts
+++ b/front_matter/create_extractor.ts
@@ -62,16 +62,16 @@ function recognize(str: string, formats?: Format[]): Format {
 }
 
 /**
- * Factory that creates a function that extracts front matter from a string with the given parsers.
- * Supports {@link https://yaml.org | YAML}, {@link https://toml.io | TOML} and
- * {@link https://www.json.org/ | JSON}.
+ * Factory that creates a function that extracts front matter from a string with
+ * the given parsers. Supports {@link https://yaml.org | YAML},
+ * {@link https://toml.io | TOML} and {@link https://www.json.org/ | JSON}.
  *
  * For simple use cases where you know which format to parse in advance, use the
  * pre-built extractors:
  *
- * - {@linkcode extractYaml}
- * - {@linkcode extractToml}
- * - {@linkcode extractJson}
+ * - {@linkcode https://jsr.io/@std/front-matter/doc/yaml/~/extract | extractYaml}
+ * - {@linkcode https://jsr.io/@std/front-matter/doc/toml/~/extract | extractToml}
+ * - {@linkcode https://jsr.io/@std/front-matter/doc/json/~/extract | extractJson}
  *
  * @param formats A descriptor containing Format-parser pairs to use for each format.
  * @returns A function that extracts front matter from a string with the given parsers.
diff --git a/front_matter/mod.ts b/front_matter/mod.ts
index 278cd05b3b6c..e67241c15ac3 100644
--- a/front_matter/mod.ts
+++ b/front_matter/mod.ts
@@ -24,7 +24,8 @@
  * result.attrs; // { and: "this" }
  * ```
  *
- * {@linkcode extractJson | extract} and {@linkcode test} support the following delimiters.
+ * {@linkcode extractJson | extract} and {@linkcode test} support the following
+ * delimiters.
  *
  * ```markdown
  * ---json
@@ -55,7 +56,8 @@
  * result.attrs; // { module: "front_matter" }
  * ```
  *
- * {@linkcode extractToml | extract} and {@linkcode test} support the following delimiters.
+ * {@linkcode extractToml | extract} and {@linkcode test} support the following
+ * delimiters.
  *
  * ```markdown
  * ---toml
@@ -92,7 +94,8 @@
  * result.attrs; // { module: "front_matter" }
  * ```
  *
- * {@linkcode extractYaml | extract} and {@linkcode test} support the following delimiters.
+ * {@linkcode extractYaml | extract} and {@linkcode test} support the following
+ * delimiters.
  *
  * ```front_matter
  * ---
diff --git a/front_matter/test.ts b/front_matter/test.ts
index 9e60a6b5e681..8366729975b6 100644
--- a/front_matter/test.ts
+++ b/front_matter/test.ts
@@ -19,12 +19,12 @@ export type { Format };
  * import { test } from "@std/front-matter/test";
  * import { assert } from "@std/assert/assert";
  *
- * const yamlValid = test(
+ * const result = test(
  * `---
  * title: Three dashes marks the spot
  * ---
  * `);
- * assert(yamlValid);
+ * assert(result);
  * ```
  *
  * @example Test for valid TOML front matter
@@ -32,12 +32,12 @@ export type { Format };
  * import { test } from "@std/front-matter/test";
  * import { assert } from "@std/assert/assert";
  *
- * const tomlValid = test(
+ * const result = test(
  * `---toml
  * title = 'Three dashes followed by format marks the spot'
  * ---
  * `);
- * assert(tomlValid);
+ * assert(result);
  * ```
  *
  * @example Test for valid JSON front matter
@@ -45,12 +45,12 @@ export type { Format };
  * import { test } from "@std/front-matter/test";
  * import { assert } from "@std/assert/assert";
  *
- * const jsonValid = test(
+ * const result = test(
  * `---json
  * {"title": "Three dashes followed by format marks the spot"}
  * ---
  * `);
- * assert(jsonValid);
+ * assert(result);
  * ```
  *
  * @example JSON front matter is not valid as YAML
@@ -58,12 +58,12 @@ export type { Format };
  * import { test } from "@std/front-matter/test";
  * import { assertFalse } from "@std/assert/assert-false";
  *
- * const parseJsonFrontMatterWithYamlFormat = test(
+ * const result = test(
  * `---json
  * {"title": "Three dashes followed by format marks the spot"}
  * ---
  * `, ["yaml"]);
- * assertFalse(parseJsonFrontMatterWithYamlFormat);
+ * assertFalse(result);
  * ```
  */
 export function test(