mdrefine 0.2.0-rc.2 → 0.2.0

package/docs/examples.md

@@ -2,20 +2,19 @@
 
 The repository's
 [`examples/`](https://github.com/viell-dev/slop-markdown-tools/tree/main/examples)
-folder holds working examples, and the npm package ships the same files under
-`node_modules/mdrefine/examples/`. The test suite compares every file and every
-output shown on this page with what the tool produces, so the page cannot drift
-from the tool's behavior.
-
-Commands are written for a
-[built checkout](quick-start.md#install-from-the-repository) and run from its
-root. With an installed package, use `npx --no-install mdtools` in place of
+directory holds working examples, and the package ships the same files under
+`node_modules/mdrefine/examples/`. The tests compare every file and output on
+this page with the tool.
+
+The commands run from the root of a [built
+checkout](https://github.com/viell-dev/slop-markdown-tools/blob/main/CONTRIBUTING.md#set-up).
+With the installed package, use `npx mdtools` in place of
 `node dist/cli/main.js`.
 
 ## Start from a configuration
 
-Four files hold a starting configuration, one for each hosting profile. Copy one
-to the root of your documents as `mdtools.config.jsonc`:
+Copy one of four starting configurations to the root of your documents as
+`mdtools.config.jsonc`:
 
 - [`examples/github.jsonc`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/github.jsonc)
   for repositories rendered by GitHub.
@@ -24,17 +23,16 @@ to the root of your documents as `mdtools.config.jsonc`:
 - [`examples/gitea.jsonc`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/gitea.jsonc)
   for Gitea instances.
 - [`examples/obsidian.jsonc`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/obsidian.jsonc)
-  for Obsidian vaults, with links written as vault-root paths.
+  for Obsidian vaults, with links written as vault-relative paths.
 
-Each wraps prose at 80 columns and chooses a link style.
-[Configuration and rules](configuration.md) explains the options.
+Each wraps prose at 80 columns and chooses a link style; see
+[configuration](configuration.md).
 
 ## Format a repository's documentation
 
 `examples/workspaces/repository-docs/` holds a README and two guides twice:
 `before/` as someone might write them, and `after/` exactly as `format --write`
-leaves them. Its configuration selects the GitHub profile and enables two rules
-that no preset turns on:
+leaves them. The configuration adds a rule that no preset enables:
 
 [`examples/workspaces/repository-docs/before/mdtools.config.jsonc`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/workspaces/repository-docs/before/mdtools.config.jsonc):
 
@@ -43,8 +41,6 @@ that no preset turns on:
   // Documentation for a repository hosted on GitHub.
   "extends": ["recommended", "github"],
   "rules": {
-    // Not part of a preset: turn underlined headings into "#" headings.
-    "style/heading": "warn",
     // Write local links as ./relative paths, which editors can follow too.
     "links/path": ["warn", { "style": "relative", "leadingDot": true }],
   },
@@ -55,7 +51,7 @@ The README before formatting:
 
 [`examples/workspaces/repository-docs/before/README.md`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/workspaces/repository-docs/before/README.md):
 
-````md
+```md
 # Weather Station
 
 Weather Station collects *temperature*, *humidity*, and *pressure* readings from a sensor board and publishes them as a small web page that updates every minute.
@@ -75,12 +71,12 @@ Follow the [setup guide](docs/guide.md) first, then read the [sensor reference](
 | Humidity | % | Yes |
 | Pressure | hPa | Since 1.2 |
 
-- [X] Publish readings every minute
-- [ ] Keep a week of history
-````
+* [X] Publish readings every minute
+* [ ] Keep a week of history
+```
 
-Preview the changes with `--diff`. To apply them with `--write`, copy `before/`
-somewhere else first so that the example stays as it is.
+Preview the changes with `--diff`. To try `--write`, copy `before/` elsewhere
+first.
 
 ```sh
 node dist/cli/main.js format --root examples/workspaces/repository-docs/before --diff
@@ -90,7 +86,7 @@ The same README afterwards:
 
 [`examples/workspaces/repository-docs/after/README.md`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/workspaces/repository-docs/after/README.md):
 
-````md
+```md
 # Weather Station
 
 Weather Station collects _temperature_, _humidity_, and _pressure_ readings from
@@ -101,8 +97,8 @@ a sensor board and publishes them as a small web page that updates every minute.
 
 ## Usage
 
-Follow the [setup guide](./docs/guide.md) first, then read the
-[sensor reference](./docs/reference.md#pressure) to interpret the readings. The
+Follow the [setup guide](./docs/guide.md) first, then read the [sensor
+reference](./docs/reference.md#pressure) to interpret the readings. The
 [calibration notes](docs/calibration.md) explain how to correct a drifting
 sensor.
 
@@ -116,7 +112,7 @@ sensor.
 
 - [x] Publish readings every minute
 - [ ] Keep a week of history
-````
+```
 
 Each change comes from one rule of the configuration:
 
@@ -124,41 +120,48 @@ Each change comes from one rule of the configuration:
   keep their lines.
 - `style/emphasis` and `style/strong` chose `_` and `**`.
 - `github/alert-marker` and `github/task-marker` normalized `[!note]` and `[X]`.
+- `style/list-marker` wrote the task list with `-`.
 - `style/table` aligned the table.
 - `links/path` put `./` in front of the links it could resolve.
 - In `docs/guide.md`, `style/heading` turned an underlined heading into a `#`
-  heading, and `docs/reference.md` gained its missing final newline.
-
-One thing did not change: the link to `docs/calibration.md`, a file that does
-not exist. Formatting never guesses a target, so linting the formatted tree
-still reports it, and exits with status `1`:
+  heading, `style/ordered-list` wrote `1)` as `1.`, `style/list-indent` left one
+  space after each number and moved the code block in the second step with the
+  step's text, and `style/code-fence` wrote the block's `~~~` fence with
+  backticks.
+- In `docs/reference.md`, `style/heading` removed the closing `##` of a heading,
+  `style/blank-lines` removed two repeated blank lines, and
+  `style/final-newline` added the missing final newline.
+
+The link to `docs/calibration.md`, a file that does not exist, did not change.
+Formatting never guesses a target, so `lint` still reports it and exits with
+code `1`:
 
 ```sh
 node dist/cli/main.js lint --root examples/workspaces/repository-docs/after
 ```
 
 ```text
-README.md:13:1: error links/valid: Missing local target: docs/calibration.md.
+examples/workspaces/repository-docs/after/README.md:13:1: error links/valid: Missing local target: docs/calibration.md.
 3 file(s) linted; 1 error(s), 0 warning(s).
 ```
 
 ## Format an Obsidian vault
 
 `examples/workspaces/obsidian-vault/` is a small vault, again as `before/` and
-`after/`. The configuration sits at the vault root, next to `.obsidian/`, whose
-`app.json` sets `"strictLineBreaks": true`; without that setting the tool
-[does not reflow prose](obsidian.md#enable-source-wrapping).
+`after/`. The configuration sits at the vault's root, next to `.obsidian/`,
+whose `app.json` sets `"strictLineBreaks": true`, which [wrapping
+needs](obsidian.md#enable-wrapping).
 
 [`examples/workspaces/obsidian-vault/before/mdtools.config.jsonc`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/workspaces/obsidian-vault/before/mdtools.config.jsonc):
 
 ```jsonc
 {
-  // An Obsidian vault; this file sits at the vault root, next to .obsidian/.
+  // An Obsidian vault; this file sits at the vault's root, next to .obsidian/.
   "extends": ["recommended", "obsidian"],
   // Templates contain placeholders, not prose. They stay valid link targets.
   "ignore": ["Templates/**"],
   "rules": {
-    // Spell Markdown links as vault-root paths in angle brackets.
+    // Spell Markdown links as vault-relative paths in angle brackets.
     "links/path": ["warn", { "style": "root", "brackets": "angle" }],
   },
 }
@@ -168,7 +171,7 @@ The vault's home note before formatting:
 
 [`examples/workspaces/obsidian-vault/before/Home.md`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/workspaces/obsidian-vault/before/Home.md):
 
-````md
+```md
 # Home
 
 This vault tracks the kitchen garden. Start with [[Tomatoes]] or jump straight to the [[Watering schedule#Summer|summer watering plan]].
@@ -182,13 +185,13 @@ This vault tracks the kitchen garden. Start with [[Tomatoes]] or jump straight t
 - [ ] Order *more* seed trays
 
 ![[Tomatoes#^harvest]]
-````
+```
 
 And afterwards:
 
 [`examples/workspaces/obsidian-vault/after/Home.md`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/workspaces/obsidian-vault/after/Home.md):
 
-````md
+```md
 # Home
 
 This vault tracks the kitchen garden. Start with [[Tomatoes]] or jump straight
@@ -205,30 +208,28 @@ to the [[Garden/Watering schedule#Summer|summer watering plan]].
 - [ ] Order _more_ seed trays
 
 ![[Garden/Tomatoes#^harvest]]
-````
+```
 
 What to notice:
 
 - The callout type is lowercase, its title stays on its line, and its body is
   wrapped inside the quote.
-- `[[Tomatoes]]` is unchanged, because rewriting an unaliased wikilink would
-  change the text a reader sees. The aliased wikilink and the embed show no
-  target, so both now carry the vault-root path.
-- The Markdown link to the template uses a vault-root path in angle brackets, as
-  `links/path` is configured. The template itself is ignored: it is never linted
-  or formatted, but links to it still resolve.
+- `[[Tomatoes]]` is unchanged, because its target is its visible text. The
+  labeled wikilink and the embed do not show their target, so both now carry the
+  vault-relative path.
+- The Markdown link to the template is vault-relative, in angle brackets. The
+  template itself is ignored: never linted or formatted, but still a link
+  target.
 - In `Garden/Tomatoes.md`, the paragraph ending in `^harvest` is not reflowed,
   because a block identifier belongs to its paragraph's last line.
-- `Garden/Watering schedule.md` links to a note named `Compost` that does not
-  exist. As in the repository example, `lint` reports it before and after
-  formatting.
+- `Garden/Watering schedule.md` links to a note `Compost` that does not exist,
+  which `lint` reports before and after formatting.
 
 ## Write a plugin
 
-`examples/plugin/` adds two house rules to the built-in ones. A problem rule
-reports placeholder words and never edits. A style rule rewrites thematic breaks
-as `---`, but only where that cannot change what the document means.
-[Plugins and library API](plugins.md) describes the contract.
+`examples/plugin/` adds two rules. A problem rule reports placeholder words. A
+style rule writes one space between a heading's `#` marks and its text, and
+leaves underlined headings alone. [Plugins](plugins.md) describes the contract.
 
 [`examples/plugin/rules.mjs`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/plugin/rules.mjs):
 
@@ -250,7 +251,7 @@ export default {
   name: "house",
   presets: {
     recommended: {
-      rules: { "house/no-placeholder": "error", "house/thematic-break": "warn" },
+      rules: { "house/no-placeholder": "error", "house/heading-space": "warn" },
     },
   },
   rules: {
@@ -292,36 +293,30 @@ export default {
         return findings;
       },
     },
-    "thematic-break": {
-      description: "Write thematic breaks as three hyphens.",
+    "heading-space": {
+      description: "Write one space between a heading's # marks and its text.",
       kind: "style",
       phase: "block",
       check({ document }) {
         const findings = [];
-        const blocks = document.tree.children;
-        // In a document whose first line is the thematic break "---", a later
-        // "---" would close it as front matter, so no break is rewritten there.
-        const opensFrontMatter =
-          blocks[0]?.type === "thematicBreak" && document.source.startsWith("---");
-        for (const [index, node] of blocks.entries()) {
-          if (node.type !== "thematicBreak") continue;
+        visit(document.tree, (node) => {
+          if (node.type !== "heading" || !node.children.length) return;
           const start = node.position.start.offset;
-          const end = node.position.end.offset;
-          if (document.source.slice(start, end) === "---") continue;
-          // "---" directly below a paragraph would turn that paragraph into a
-          // heading. Only propose the edit after a blank line, where it cannot.
-          const previous = blocks[index - 1];
-          const safe =
-            !opensFrontMatter &&
-            previous &&
-            previous.position.end.line < node.position.start.line - 1;
+          const text = node.children[0].position.start.offset;
+          const marks = document.source.slice(start, text);
+          const wanted = `${"#".repeat(node.depth)} `;
+          // Only a "#" heading starts with its marks: an underlined heading
+          // starts with its text, and so the check below leaves it alone. The
+          // parser drops the blank space before a heading's text, so changing
+          // it cannot change what the heading says.
+          if (!/^#+[ \t]+$/.test(marks) || marks === wanted) return;
           findings.push({
             start,
-            end,
-            message: "Write this thematic break as ---.",
-            ...(safe ? { edit: { start, end, text: "---" } } : {}),
+            end: text,
+            message: "Write one space after the heading's # marks.",
+            edit: { start, end: text, text: wanted },
           });
-        }
+        });
         return findings;
       },
     },
@@ -329,8 +324,8 @@ export default {
 };
 ```
 
-The configuration loads the plugin, enables its preset, and passes options to
-one rule:
+The configuration loads the plugin, enables its preset, and sets one rule's
+options:
 
 [`examples/plugin/mdtools.config.jsonc`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/plugin/mdtools.config.jsonc):
 
@@ -350,32 +345,31 @@ A note that triggers both rules:
 
 [`examples/plugin/notes/release-checklist.md`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/plugin/notes/release-checklist.md):
 
-````md
+```md
 # Release checklist
 
 Draft the announcement. TODO: add the download link.
 
 Searching the notes with `grep TODO` is not reported: code is not prose.
 
-***
+##   Before publishing
 
-Ask for a review before publishing.
-````
+Ask for a review.
+```
 
-Linting reports both, and does not report the `TODO` inside the code span:
+Linting reports both, but not the `TODO` inside the code span:
 
 ```sh
 node dist/cli/main.js lint --root examples/plugin
 ```
 
 ```text
-notes/release-checklist.md:3:25: error house/no-placeholder: Replace the placeholder "TODO" before publishing.
-notes/release-checklist.md:7:1: warn house/thematic-break: Write this thematic break as ---.
+examples/plugin/notes/release-checklist.md:3:25: error house/no-placeholder: Replace the placeholder "TODO" before publishing.
+examples/plugin/notes/release-checklist.md:7:1: warn house/heading-space: Write one space after the heading's # marks.
 1 file(s) linted; 1 error(s), 1 warning(s).
 ```
 
-Formatting applies the style rule's edit and leaves the placeholder for a
-person:
+Formatting applies the style rule's edit and leaves the placeholder to a person:
 
 ```sh
 node dist/cli/main.js format --root examples/plugin --diff
@@ -383,24 +377,24 @@ node dist/cli/main.js format --root examples/plugin --diff
 
 ```text
 ===================================================================
---- a/notes/release-checklist.md
-+++ b/notes/release-checklist.md
+--- a/examples/plugin/notes/release-checklist.md
++++ b/examples/plugin/notes/release-checklist.md
 @@ -3,7 +3,7 @@
  Draft the announcement. TODO: add the download link.
  
  Searching the notes with `grep TODO` is not reported: code is not prose.
  
--***
-+---
+-##   Before publishing
++## Before publishing
  
- Ask for a review before publishing.
-notes/release-checklist.md:3:25: error house/no-placeholder: Replace the placeholder "TODO" before publishing.
+ Ask for a review.
+examples/plugin/notes/release-checklist.md:3:25: error house/no-placeholder: Replace the placeholder "TODO" before publishing.
 1 file(s) processed; 1 would change.
 ```
 
 ## Call the library
 
-The library takes strings and returns strings; it never reads or writes files.
+The [library](api.md) takes and returns strings; it never reads or writes files.
 The scripts import `mdrefine` by name, which works in a checkout and wherever
 the package is installed.
 
@@ -441,7 +435,7 @@ no final newline.
 changed: true; remaining diagnostics: 0
 ```
 
-To check links between documents, the host reads the files and passes them to
+To check links between documents, the script reads the files and passes them to
 `createWorkspace()`:
 
 [`examples/library/lint-folder.mjs`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/library/lint-folder.mjs):
@@ -452,7 +446,8 @@ To check links between documents, the host reads the files and passes them to
 // The library never reads or writes files. The host reads them and hands them
 // to createWorkspace(), which is what lets rules check links between documents.
 // This script reads everything below the folder; a real host would skip folders
-// such as .git and node_modules, as the CLI does.
+// such as .git and node_modules, as the CLI does. lint-workspace.mjs leaves that
+// to discoverWorkspace() from "mdrefine/node".
 //
 //   node examples/library/lint-folder.mjs [folder]
 import { readdir, readFile } from "node:fs/promises";
@@ -466,14 +461,14 @@ const folder = path.resolve(
 const config = { extends: ["recommended", "github"] };
 
 // Workspace keys are forward-slash paths relative to the folder. A Markdown
-// file maps to its text; any other file maps to null, so that links to it
-// still resolve.
+// file, named .md or .markdown as the CLI finds them, maps to its text; any
+// other file maps to null, so that links to it still resolve.
 const files = {};
 for (const entry of await readdir(folder, { recursive: true, withFileTypes: true })) {
   if (!entry.isFile()) continue;
   const absolute = path.join(entry.parentPath, entry.name);
   const name = path.relative(folder, absolute).split(path.sep).join("/");
-  files[name] = /\.md$/i.test(name) ? await readFile(absolute, "utf8") : null;
+  files[name] = /\.(?:md|markdown)$/i.test(name) ? await readFile(absolute, "utf8") : null;
 }
 const workspace = createWorkspace(files, { dialect: "github" });
 
@@ -504,10 +499,60 @@ README.md:13:1 error links/valid: Missing local target: docs/calibration.md.
 1 error(s)
 ```
 
+`mdrefine/node` finds and selects the files as the CLI does, and prepares each
+document's options:
+
+[`examples/library/lint-workspace.mjs`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/library/lint-workspace.mjs):
+
+```js
+// Lint a workspace on disk through the library, choosing files as the CLI does.
+//
+// discoverWorkspace() from "mdrefine/node" finds the files, honors .gitignore
+// files and the configuration's ignore patterns, leaves out nested
+// repositories and what it may not read, and recognizes Obsidian vaults.
+// options() then gives each document what the CLI passes to lint() and
+// format(). Configuration files are not read: pass the configuration.
+//
+//   node examples/library/lint-workspace.mjs [folder]
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { lint } from "mdrefine";
+import { discoverWorkspace } from "mdrefine/node";
+
+const root = path.resolve(
+  process.argv[2] ?? fileURLToPath(new URL("../workspaces/repository-docs/after", import.meta.url)),
+);
+const config = { extends: ["recommended", "github"] };
+
+const discovery = await discoverWorkspace({ root, config });
+for (const item of discovery.skipped) console.log(`skipped: ${item.message}`);
+let errors = 0;
+for (const name of discovery.selected) {
+  for (const item of lint(discovery.read(name), discovery.options(name))) {
+    if (item.severity === "error") errors += 1;
+    console.log(
+      `${name}:${item.line}:${item.column} ${item.severity} ${item.rule}: ${item.message}`,
+    );
+  }
+}
+console.log(`${errors} error(s) in ${discovery.selected.length} document(s)`);
+process.exitCode = errors > 0 ? 1 : 0;
+```
+
+```sh
+node examples/library/lint-workspace.mjs
+```
+
+```text
+README.md:13:1 error links/valid: Missing local target: docs/calibration.md.
+1 error(s) in 3 document(s)
+```
+
 ## Automate checks
 
-A workflow for a repository that lists `mdrefine` in its `devDependencies` and
-has an `mdtools.config.jsonc` at its root:
+A GitHub Actions workflow for a repository that lists `mdrefine` in its
+`devDependencies`; [integrations](integrations.md#continuous-integration) covers
+Forgejo:
 
 [`examples/automation/github-actions.yml`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/automation/github-actions.yml):
 
@@ -537,9 +582,9 @@ jobs:
       - run: npx --no-install mdtools format --check
 ```
 
-For scripts and agents, `--json` prints one report object instead of text.
+The script
 [`summarize-report.mjs`](https://github.com/viell-dev/slop-markdown-tools/blob/main/examples/automation/summarize-report.mjs)
-reads that report and counts diagnostics per rule:
+reads a `--json` report and counts diagnostics per rule:
 
 ```sh
 node dist/cli/main.js lint --root examples/plugin --json | node examples/automation/summarize-report.mjs
@@ -548,8 +593,5 @@ node dist/cli/main.js lint --root examples/plugin --json | node examples/automat
 ```text
 lint: 1 file(s), 2 diagnostic(s)
 1 error house/no-placeholder in 1 file(s)
-1 warn house/thematic-break in 1 file(s)
+1 warn house/heading-space in 1 file(s)
 ```
-
-[CLI workflows](cli.md) covers file selection, exit codes, and stdin;
-[configuration and rules](configuration.md) lists every rule and option.

package/docs/index.md

@@ -1,52 +1,36 @@
 ---
 layout: home
 hero:
-  name: Markdown Tools
-  text: Your Markdown. Your rules.
-  tagline: Separate lint and format commands. Shared configuration. Built for CommonMark, GitHub, Forgejo, Gitea, and Obsidian.
+  name: mdrefine
+  text: Lint and format Markdown
+  tagline: One configuration for checks and formatting, for documents rendered by GitHub, Forgejo, Gitea, Obsidian, or any CommonMark renderer.
   actions:
     - theme: brand
-      text: Quick start
+      text: Get started
       link: /quick-start
     - theme: alt
-      text: Explore the rules
-      link: /configuration
+      text: Rules
+      link: /rules
 features:
   - title: Check, preview, then write
-    details: Lint without changing files, inspect formatting diffs, and write when ready. JSON diagnostics work with agents and automation.
-  - title: Format what you configure
-    details: Wrap at 80 columns by default. Choose link paths, delimiters, and dialect rules. Disabled rules preserve their syntax choices.
-  - title: Extend the shared core
-    details: Add JavaScript rules, presets, and syntax extensions. Use the same engine through the CLI or the TypeScript library.
+    details: Lint without changing files, read the diff, and write when ready. A JSON report and exit codes serve CI, scripts, and agents.
+  - title: Changes only what its rules target
+    details: Formatting edits the source in place, keeps everything else byte for byte, and refuses an edit that would change what a document means.
+  - title: Knows where it renders
+    details: Tables, math, wikilinks, callouts, and heading anchors are read as GitHub, Forgejo, Gitea, or Obsidian read them, and local links are checked the same way.
 ---
 
-## A small, reviewable workflow
-
-From a [built checkout](quick-start.md), point the CLI at your documents:
+mdrefine is meant to replace a general-purpose linter and formatter, such as
+markdownlint and Prettier, for Markdown documents.
+[Integrations](integrations.md#coming-from-prettier-or-markdownlint) shows which
+of their checks have a rule here so far.
 
 ```sh
-node dist/cli/main.js lint --root /path/to/documents
-node dist/cli/main.js format --root /path/to/documents --diff
-node dist/cli/main.js format --root /path/to/documents --write
+npx mdtools lint
+npx mdtools format --diff
+npx mdtools format --write
+npx mdtools format --check
 ```
 
-Formatting applies edits to the original source and checks the parsed meaning
-before accepting them. See the [safety boundaries](design.md#safety-boundaries)
-for the limits of those checks.
-
-## Start with your documents
-
-- **A repository or writing folder:** follow the [quick start](quick-start.md),
-  then choose [configuration and rules](configuration.md).
-- **An Obsidian vault:** use the [vault guide](obsidian.md) for wikilinks,
-  callouts, block references, and safe prose wrapping.
-- **A custom workflow:** use [CLI workflows](cli.md) or extend the
-  [library and plugin API](plugins.md).
-- **A look before installing:** the [examples](examples.md) show documents
-  before and after formatting, a plugin, and library scripts.
-
-This is an early prerelease, written, tested, documented, and maintained by AI
-agents rather than human maintainers. The repository owner assigns agents to
-tasks and follows the project through issues and PRs, not code. Issues and pull
-requests from people and agents are welcome. Read
-[how to contribute](contributing.md) before reporting a defect.
+[Get started](quick-start.md), browse the [rules](rules.md), or see
+[examples](examples.md) of documents before and after formatting.