docs(front_matter): cleanup and improve docs (#4505)

crypto/crypto.ts

@@ -57,7 +57,6 @@
  * - `MD4` (collidable and length-extendable)
  * - `MD5` (collidable and length-extendable)
  * - `SHA-1` (collidable and length-extendable)
- * ```
  *
  * @example
  * ```ts

front_matter/any.ts

@@ -8,6 +8,28 @@ import {
 import { parse as parseYAML } from "../yaml/parse.ts";
 import { parse as parseTOML } from "../toml/parse.ts";
 
+/**
+ * Extracts and parses {@link https://yaml.org | YAML}, {@link https://toml.io |
+ * TOML}, or {@link https://www.json.org/ | JSON} from the metadata of front
+ * matter content, depending on the format.
+ *
+ * @example
+ * ```ts
+ * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/any.ts";
+ *
+ * const output = `---json
+ * {
+ *   "title": "Three dashes marks the spot"
+ * }
+ * ---
+ * 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" }
+ * ```
+ */
 export const extract: Extractor = createExtractor({
   yaml: parseYAML as Parser,
   toml: parseTOML as Parser,

front_matter/json.ts

@@ -6,6 +6,27 @@ import {
   type Parser,
 } from "./create_extractor.ts";
 
+/**
+ * Extracts and parses {@link https://www.json.org/ | JSON } from the metadata
+ * of front matter content.
+ *
+ * @example
+ * ```ts
+ * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/json.ts";
+ *
+ * const output = `---json
+ * {
+ *   "title": "Three dashes marks the spot"
+ * }
+ * ---
+ * 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" }
+ * ```
+ */
 export const extract: Extractor = createExtractor({
   json: JSON.parse as Parser,
 });

front_matter/mod.ts

@@ -1,117 +1,62 @@
+// deno-lint-ignore-file no-unused-vars
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // Copyright (c) Jason Campbell. MIT license
 
 /**
  * Extracts
  * {@link https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/ | front matter}
- * from strings.
- *
- * {@linkcode createExtractor} and {@linkcode test} functions
- * to handle many forms of front matter.
- *
- * Adapted from
+ * from strings. Adapted from
  * {@link https://github.com/jxson/front-matter/blob/36f139ef797bd9e5196a9ede03ef481d7fbca18e/index.js | jxson/front-matter}.
  *
- * Supported formats:
- *
- * - [`YAML`](./front_matter/yaml.ts)
- * - [`TOML`](./front_matter/toml.ts)
- * - [`JSON`](./front_matter/json.ts)
+ * ## Supported formats
  *
- * ### Basic usage
- *
- * example.md
- *
- * ```markdown
- * ---
- * module: front_matter
- * tags:
- *   - yaml
- *   - toml
- *   - json
- * ---
- *
- * deno is awesome
- * ```
- *
- * example.ts
+ * ### JSON
  *
  * ```ts
- * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/any.ts";
  * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts";
+ * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/json.ts";
  *
- * const str = await Deno.readTextFile("./example.md");
+ * const str = "---json\n{\"and\": \"this\"}\n---\ndeno is awesome";
+ * const result = extract(str);
  *
- * if (test(str)) {
- *   console.log(extract(str));
- * } else {
- *   console.log("document doesn't contain front matter");
- * }
+ * test(str); // true
+ * result.frontMatter; // "{\"and\": \"this\"}"
+ * result.body; // "deno is awesome"
+ * result.attrs; // { and: "this" }
  * ```
  *
- * ```sh
- * $ deno run ./example.ts
+ * {@linkcode extractJson | extract} and {@linkcode test} support the following delimiters.
+ *
+ * ```markdown
+ * ---json
  * {
- *   frontMatter: "module: front_matter\ntags:\n  - yaml\n  - toml\n  - json",
- *   body: "deno is awesome",
- *   attrs: { module: "front_matter", tags: [ "yaml", "toml", "json" ] }
+ *   "and": "this"
  * }
+ * ---
  * ```
  *
- * The above example recognizes any of the supported formats, extracts metadata and
- * parses accordingly. Please note that in this case both the [YAML](#yaml) and
- * [TOML](#toml) parsers will be imported as dependencies.
- *
- * If you need only one specific format then you can import the file named
- * respectively from [here](./front_matter).
- *
- * ### Advanced usage
- *
- * ```ts
- * import { test as _test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts";
- * import {
- *   createExtractor,
- *   Parser,
- * } from "https://deno.land/std@$STD_VERSION/front_matter/mod.ts";
- * import { parse } from "https://deno.land/std@$STD_VERSION/toml/parse.ts";
- *
- * const extract = createExtractor({
- *   "toml": parse as Parser,
- *   "json": JSON.parse as Parser,
- * });
- *
- * export function test(str: string): boolean {
- *   return _test(str, ["toml", "json"]);
+ * ```markdown
+ * {
+ *   "is": "JSON"
  * }
  * ```
  *
- * In this setup `extract()` and `test()` will work with TOML and JSON and only.
- * This way the YAML parser is not loaded if not needed. You can cherry-pick which
- * combination of formats are you supporting based on your needs.
- *
- * ### Delimiters
+ * ### TOML
  *
- * #### YAML
- *
- * ```markdown
- * ---
- * these: are
- * ---
- * ```
+ * ```ts
+ * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts";
+ * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/toml.ts";
  *
- * ```markdown
- * ---yaml
- * all: recognized
- * ---
- * ```
+ * const str = "---toml\nmodule = 'front_matter'\n---\ndeno is awesome";
+ * const result = extract(str);
  *
- * ```markdown
- * = yaml =
- * as: yaml
- * = yaml =
+ * test(str); // true
+ * result.frontMatter; // "module = 'front_matter'"
+ * result.body; // "deno is awesome"
+ * result.attrs; // { module: "front_matter" }
  * ```
  *
- * #### TOML
+ * {@linkcode extractToml | extract} and {@linkcode test} support the following delimiters.
  *
  * ```markdown
  * ---toml
@@ -133,24 +78,46 @@
  * +++
  * ```
  *
- * #### JSON
+ * ### YAML
+ *
+ * ```ts
+ * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts";
+ * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/yaml.ts";
+ *
+ * const str = "---yaml\nmodule: front_matter\n---\ndeno is awesome";
+ * const result = extract(str);
+ *
+ * test(str); // true
+ * result.frontMatter; // "module: front_matter"
+ * result.body; // "deno is awesome"
+ * result.attrs; // { module: "front_matter" }
+ * ```
+ *
+ * {@linkcode extractYaml | extract} and {@linkcode test} support the following delimiters.
+ *
+ * ```front_matter
+ * ---
+ * these: are
+ * ---
+ * ```
  *
  * ```markdown
- * ---json
- * {
- *   "and": "this"
- * }
+ * ---yaml
+ * all: recognized
  * ---
  * ```
  *
  * ```markdown
- * {
- *   "is": "JSON"
- * }
+ * = yaml =
+ * as: yaml
+ * = yaml =
  * ```
  *
  * @module
  */
+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";

front_matter/test.ts

@@ -2,7 +2,7 @@
 
 import { EXTRACT_REGEXP_MAP } from "./_formats.ts";
 
-type Format = "yaml" | "toml" | "json" | "unknown";
+export type Format = "yaml" | "toml" | "json" | "unknown";
 
 /**
  * Tests if a string has valid front matter. Supports YAML, TOML and JSON.
@@ -11,19 +11,17 @@ type Format = "yaml" | "toml" | "json" | "unknown";
  * @param formats A list of formats to test for. Defaults to all supported formats.
  *
  * ```ts
- * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/mod.ts";
- * import { assert } from "https://deno.land/std@$STD_VERSION/assert/assert.ts";
+ * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts";
  *
- * assert(test("---\ntitle: Three dashes marks the spot\n---\n"));
- * assert(test("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n"));
- * assert(test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n"));
- *
- * assert(!test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n", ["yaml"]));
+ * 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
  * ```
  */
 export function test(
   str: string,
-  formats?: ("yaml" | "toml" | "json" | "unknown")[],
+  formats?: Format[],
 ): boolean {
   if (!formats) {
     formats = Object.keys(EXTRACT_REGEXP_MAP) as Format[];

front_matter/toml.ts

@@ -7,6 +7,25 @@ import {
 } from "./create_extractor.ts";
 import { parse } from "../toml/parse.ts";
 
+/**
+ * Extracts and parses {@link https://toml.io | TOML} from the metadata of
+ * front matter content.
+ *
+ * @example
+ * ```ts
+ * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/toml.ts";
+ *
+ * const output = `---toml
+ * title = "Three dashes marks the spot"
+ * ---
+ * 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" }
+ * ```
+ */
 export const extract: Extractor = createExtractor({
   ["toml"]: parse as Parser,
 });

front_matter/yaml.ts

@@ -7,6 +7,25 @@ import {
 } from "./create_extractor.ts";
 import { parse } from "../yaml/parse.ts";
 
+/**
+ * Extracts and parses {@link https://yaml.org | YAML} from the metadata of
+ * front matter content.
+ *
+ * @example
+ * ```ts
+ * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/yaml.ts";
+ *
+ * const output = `---yaml
+ * title: Three dashes marks the spot
+ * ---
+ * 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" }
+ * ```
+ */
 export const extract: Extractor = createExtractor({
   ["yaml"]: parse as Parser,
 });