mdat 0.1.0

package/bin/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import{defaultLoaders as S}from"cosmiconfig";function b(e,o){let n=S[".json"],d=n(e,o);return O(d)}function O(e,o="",n={}){for(let[d,r]of Object.entries(e)){let t=o?`${o}.${d}`:d;typeof r=="object"&&r!==null&&!Array.isArray(r)?O(r,t,n):r===null?n[t]="null":n[t]=r.toString()}return n}import C from"chalk";import{cosmiconfig as R}from"cosmiconfig";import I from"node:fs/promises";import J from"node:path";import L from"plur";import{deepMergeDefined as w,log as m,optionsSchema as V,rulesSchema as N}from"remark-mdat";async function v(e){let{additionalConfig:o,additionalRules:n,configExtensionSchema:d,searchFrom:r}=e??{},t={},a=V;d!==void 0&&(a=a.merge(d));let f=R("mdat"),p=await f.search(r);if(p){let{config:u,filepath:s}=p;m.info(`Using config from "${s}"`);let i=k(u,a);i&&(t=w(t,i))}if(o!==void 0){let u=Array.isArray(o)?o:[o];for(let s of u){let i;if(typeof s=="string"){let c=await f.load(s);if(c==null)continue;let{config:l,filepath:x}=c;m.info(`Loaded additional config from "${x}"`),i=l}else i=s;if(i===void 0)continue;m.info("Merging configuration object");let g=k(i,a);g!==void 0&&(t=w(t,g))}}if(n!==void 0){let u=Array.isArray(n)?n:[n],s=R("mdat",{loaders:{".json":b}});for(let i of u){let g;if(typeof i=="string"){let l;if(J.basename(i).endsWith("package.json")){let F=await I.readFile(i,"utf8");l={config:b(i,F),filepath:i}}else l=await s.load(i);if(l==null)continue;let{config:x,filepath:A}=l;m.info(`Loaded additional config from "${A}"`),g=x}else g=i;if(g===void 0)continue;m.info("Merging rules into configuration object");let c=z(g,N);c!==void 0&&(t=w(t,c))}}if(t.rules){let u=Object.keys(t.rules).sort().map(s=>`"${C.bold.green(s)}"`);m.info(`Loaded ${C.bold(u.length)} mdat comment expansion ${L("rule",u.length)}:`);for(let s of u)m.info(`	${s}`)}else m.error("No rules loaded from additional configurations or rules, using default.");return t}function z(e,o){if(o.safeParse(e).success)return{rules:e};m.error(`Rules object has the wrong shape. Ignoring and using default configuration:
+${JSON.stringify(e,void 0,2)}`)}function k(e,o){if(o.safeParse(e).success)return e;m.error(`Config object has the wrong shape. Ignoring and using default configuration:
+${JSON.stringify(e,void 0,2)}`)}import D from"node:fs";import h from"node:path";import{isFileSync as M}from"path-type";import Z from"untildify";function U(e,o){let n=o===0?1:Math.floor(Math.log10(Math.abs(o))+1);return e.toString().padStart(n,"0")}function $(e,o,n,d){let r=[];for(let[t,a]of e.entries()){let f=n&&e.length>1?`-${U(t+1,e.length+1)}`:"",p=E(a,o,n,d,f);r.push(p)}return r}function E(e,o,n,d,r=""){let t=P(e),a=o?P(o):void 0;if(!M(t))throw new Error(`Input file not found: "${t}"`);if(a){if(M(a))throw new Error(`Output path must be a directory, received a file path: "${a}"`);D.mkdirSync(a,{recursive:!0})}let f=n?h.basename(n,h.extname(n)):h.basename(t,h.extname(t)),p=`.${d??(n&&h.extname(n)!==""?h.extname(n):h.extname(e)===""?"":h.extname(e))}`,u=`${f}${r}${p}`,s=a??h.dirname(t);return{input:t,name:u,output:s}}function P(e){return Z(e)}import{remark as W}from"remark";import q from"remark-gfm";import{default as B}from"remark-mdat";import{read as G}from"to-vfile";import{VFile as Me}from"vfile";async function j(e,o,n,d,r){let t=await v({additionalConfig:d,additionalRules:r}),a=$(e,n,o,"md"),f=[],p=Y(t);for(let{input:u,name:s,output:i}of a){let g=await G(u),c=await p.process(g);c.dirname=i,c.basename=s,f.push(c)}return f}function Y(e){return W().use({settings:{bullet:"-",emphasis:"_"}}).use(q).use(B,e??{})}import _ from"plur";import H from"pretty-ms";import{getMdatReports as Q,log as y,reporterMdat as X}from"remark-mdat";import{write as K}from"to-vfile";import ee from"yargs";import{hideBin as ne}from"yargs/helpers";var te=performance.now(),T=ee(ne(process.argv));try{await T.scriptName("mdat").usage("$0 [command] [options]","Note: `expand` is the default and only command at the moment.").command(["$0 <files..> [options]","expand <files..> [options]"],"Expand comment placeholders in Markdown files.",e=>e.positional("files",{array:!0,demandOption:!0,describe:"Markdown file(s) with `mdat` placeholder comments to expand.",type:"string"}).option("config",{defaultDescription:"Configuration is loaded if found from the usual places, or defaults are used.",description:"Path(s) to files containing mdat configs.",string:!0,type:"array"}).option("rules",{alias:"r",description:"Path(s) to files containing `mdat` comment expansion rules.",string:!0,type:"array"}).option("output",{alias:"o",defaultDescription:"Same directory as input file.",description:"Output file directory.",type:"string"}).option("name",{alias:"n",defaultDescription:"Same name as input file. Overwrites the input file.",description:"Output file name.",type:"string"}).option("print",{default:!1,description:"Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.",type:"boolean"}).option("prefix",{description:"Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-`mdat` comments in your Markdown file, or if you're willing to trade some verbosity for safety.",type:"string"}).option("meta",{alias:"m",default:!1,description:"Embed an extra comment at the top of the generated Markdown noting the date of generation and warning editors that certain sections of the document have been generated dynamically.",type:"boolean"}).option("check",{alias:"c",default:!1,describe:"Check the input files for rule violations without expanding them. Identifies things like missing comment placeholders and incorrect placeholder ordering.",type:"boolean"}).option("verbose",{default:!1,describe:"Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.",type:"boolean"}),async({check:e,config:o,files:n,meta:d,name:r,output:t,prefix:a="",print:f,rules:p,verbose:u})=>{y.verbose=u,e&&(t&&(t=void 0,y.warn("Ignoring --output option because --check is set")),r&&(r=void 0,y.warn("Ignoring --name option because --check is set")),f&&(f=!1,y.warn("Ignoring --print option because --check is set"))),f&&(t&&(t=void 0,y.warn("Ignoring --output option because --print is set")),r&&(r=void 0,y.warn("Ignoring --name option because --print is set")));let s=[...o??[],{addMetaComment:d,keywordPrefix:a}];Array.isArray(n)||(n=[n]);let i=await j(n,r,t,s,p);if(f)for(let l of i)process.stdout.write(l.toString());if(X(i),!e&&!f)for(let l of i)await K(l);let c=Q(i).reduce((l,x)=>l+x.errors.length,0);y.info(`Expanded comments in ${n.length} ${_("file",n.length)} in ${H(performance.now()-te)}.`),process.exitCode=c>0?1:0}).help().alias("h","help").version().alias("v","version").wrap(process.stdout.isTTY?Math.min(120,T.terminalWidth()):0).fail(!1).parse()}catch(e){e instanceof Error&&y.error(e.message),process.exitCode=1}

package/dist/api.d.ts

@@ -0,0 +1,22 @@
+import { type Options as MdatOptions, type Rules } from 'remark-mdat';
+import { VFile } from 'vfile';
+/**
+ * Generously accept either string paths to .ts, .js, or .json files with
+ * `MdatOptions` type default exports. Takes a single value, or an array of values which
+ * will be merged right to left.
+ */
+export type ExpandConfig<T extends MdatOptions = MdatOptions> = Array<T | string> | T | string;
+/**
+ * Generously accept either string paths to .ts, .js, or .json files with
+ * `Rules` type default exports.
+ */
+export type ExpandRules = Array<Rules | string> | Rules | string;
+/**
+ * Writing is the responsibility of the caller (e.g. via `await write(result)`)
+ */
+export declare function expandFiles(files: string[], name?: string, output?: string, config?: ExpandConfig, rules?: ExpandRules): Promise<VFile[]>;
+/**
+ * Writing is the responsibility of the caller (e.g. via `await write(result)`)
+ */
+export declare function expandFile(file: string, name?: string, output?: string, config?: ExpandConfig, rules?: ExpandRules): Promise<VFile>;
+export declare function expandString(markdown: string, config?: ExpandConfig, rules?: ExpandRules): Promise<VFile>;

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+import { type Options, type Rules } from 'remark-mdat';
+import { type z } from 'zod';
+export type MdatConfig = Options;
+/**
+ * Load and validate mdat configuration / rule sets
+ * Uses cosmiconfig to search in the usual places.
+ * Merge precedence: Additional Config Paths < Search Path < mdat-remark defaults
+ *
+ * Generic to accommodate additional Config options, so set T to your custom config type if needed. You must provide a matching configExtensionSchema as well.
+ */
+export declare function loadConfig<T extends MdatConfig>(options?: {
+    /**
+     * Additional Config objects to merge.
+     *
+     * Strings are treated as paths to `ts`, `js`, or `json` files with `Config` type default exports. These will be dynamically loaded by Cosmiconfig.
+     * Accepts an individual item, or an array. Objects in the array will be merged right to left.
+     *
+     */
+    additionalConfig?: Array<T | string> | T | string | undefined;
+    /**
+     * Additional Rules objects to merge.
+     *
+     * Strings are treated as paths to `ts`, `js`, or `json` files with `Rules` type default exports. These will be dynamically loaded by Cosmiconfig.
+     * Accepts an individual item, or an array. Objects in the array will be merged right to left, and take precedence over any rules in previously loaded Config objects as well.
+     */
+    additionalRules?: Array<Rules | string> | Rules | string | undefined;
+    /** Additional zod schema that will be merged with the top level of the config schema and used for config validation. Default mdat-remark options schema is used if not provided. Useful if extending config for things like mdat-readme. */
+    configExtensionSchema?: z.ZodObject<any>;
+    /** Search for config in specific directories, mainly useful for testing. Cosmiconfig default search paths used if unset. */
+    searchFrom?: string;
+}): Promise<T>;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { type ExpandConfig, type ExpandRules, expandFile, expandFiles, expandString } from './api';
+export { type MdatConfig, loadConfig } from './config';

package/dist/index.js

@@ -0,0 +1,3 @@
+import{defaultLoaders as M}from"cosmiconfig";function O(n,e){let t=M[".json"],r=t(n,e);return w(r)}function w(n,e="",t={}){for(let[r,s]of Object.entries(n)){let o=e?`${e}.${r}`:r;typeof s=="object"&&s!==null&&!Array.isArray(s)?w(s,o,t):s===null?t[o]="null":t[o]=s.toString()}return t}import j from"chalk";import{cosmiconfig as F}from"cosmiconfig";import k from"node:fs/promises";import v from"node:path";import L from"plur";import{deepMergeDefined as b,log as p,optionsSchema as V,rulesSchema as I}from"remark-mdat";async function x(n){let{additionalConfig:e,additionalRules:t,configExtensionSchema:r,searchFrom:s}=n??{},o={},i=V;r!==void 0&&(i=i.merge(r));let l=F("mdat"),d=await l.search(s);if(d){let{config:u,filepath:f}=d;p.info(`Using config from "${f}"`);let a=P(u,i);a&&(o=b(o,a))}if(e!==void 0){let u=Array.isArray(e)?e:[e];for(let f of u){let a;if(typeof f=="string"){let c=await l.load(f);if(c==null)continue;let{config:h,filepath:y}=c;p.info(`Loaded additional config from "${y}"`),a=h}else a=f;if(a===void 0)continue;p.info("Merging configuration object");let g=P(a,i);g!==void 0&&(o=b(o,g))}}if(t!==void 0){let u=Array.isArray(t)?t:[t],f=F("mdat",{loaders:{".json":O}});for(let a of u){let g;if(typeof a=="string"){let h;if(v.basename(a).endsWith("package.json")){let J=await k.readFile(a,"utf8");h={config:O(a,J),filepath:a}}else h=await f.load(a);if(h==null)continue;let{config:y,filepath:A}=h;p.info(`Loaded additional config from "${A}"`),g=y}else g=a;if(g===void 0)continue;p.info("Merging rules into configuration object");let c=z(g,I);c!==void 0&&(o=b(o,c))}}if(o.rules){let u=Object.keys(o.rules).sort().map(f=>`"${j.bold.green(f)}"`);p.info(`Loaded ${j.bold(u.length)} mdat comment expansion ${L("rule",u.length)}:`);for(let f of u)p.info(`	${f}`)}else p.error("No rules loaded from additional configurations or rules, using default.");return o}function z(n,e){if(e.safeParse(n).success)return{rules:n};p.error(`Rules object has the wrong shape. Ignoring and using default configuration:
+${JSON.stringify(n,void 0,2)}`)}function P(n,e){if(e.safeParse(n).success)return n;p.error(`Config object has the wrong shape. Ignoring and using default configuration:
+${JSON.stringify(n,void 0,2)}`)}import N from"node:fs";import m from"node:path";import{isFileSync as $}from"path-type";import Z from"untildify";function D(n,e){let t=e===0?1:Math.floor(Math.log10(Math.abs(e))+1);return n.toString().padStart(t,"0")}function S(n,e,t,r){let s=[];for(let[o,i]of n.entries()){let l=t&&n.length>1?`-${D(o+1,n.length+1)}`:"",d=R(i,e,t,r,l);s.push(d)}return s}function R(n,e,t,r,s=""){let o=E(n),i=e?E(e):void 0;if(!$(o))throw new Error(`Input file not found: "${o}"`);if(i){if($(i))throw new Error(`Output path must be a directory, received a file path: "${i}"`);N.mkdirSync(i,{recursive:!0})}let l=t?m.basename(t,m.extname(t)):m.basename(o,m.extname(o)),d=`.${r??(t&&m.extname(t)!==""?m.extname(t):m.extname(n)===""?"":m.extname(n))}`,u=`${l}${s}${d}`,f=i??m.dirname(o);return{input:o,name:u,output:f}}function E(n){return Z(n)}import{remark as G}from"remark";import U from"remark-gfm";import{default as W}from"remark-mdat";import{read as T}from"to-vfile";import{VFile as _}from"vfile";async function q(n,e,t,r,s){let o=await x({additionalConfig:r,additionalRules:s}),i=S(n,t,e,"md"),l=[],d=C(o);for(let{input:u,name:f,output:a}of i){let g=await T(u),c=await d.process(g);c.dirname=a,c.basename=f,l.push(c)}return l}async function B(n,e,t,r,s){let o=await x({additionalConfig:r,additionalRules:s}),i=R(n,t,e,"md"),l=await T(i.input),d=await C(o).process(l);return d.dirname=i.output,d.basename=i.name,d}async function H(n,e,t){let r=await x({additionalConfig:e,additionalRules:t});return C(r).process(new _(n))}function C(n){return G().use({settings:{bullet:"-",emphasis:"_"}}).use(U).use(W,n??{})}export{B as expandFile,q as expandFiles,H as expandString,x as loadConfig};

package/dist/mdat-json-loader.d.ts

@@ -0,0 +1,2 @@
+import { type LoaderResult } from 'cosmiconfig';
+export declare function mdatJsonLoader(filePath: string, content: string): LoaderResult;

package/dist/utilities.d.ts

@@ -0,0 +1,11 @@
+export declare function getInputOutputPaths(inputs: string[], output: string | undefined, name: string | undefined, extension: string | undefined): Array<{
+    input: string;
+    name: string;
+    output: string;
+}>;
+export declare function getInputOutputPath(input: string, output: string | undefined, name: string | undefined, extension: string | undefined, nameSuffix?: string): {
+    input: string;
+    name: string;
+    output: string;
+};
+export declare function expandPath(file: string): string;

package/license.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Eric Mika
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "mdat",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CLI tool and library for using comments as content templates in Markdown files.",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:kitschpatrol/mdat.git",
+    "directory": "packages/mdat"
+  },
+  "bugs": {
+    "url": "https://github.com/kitschpatrol/mdat/issues",
+    "email": "eric@ericmika.com"
+  },
+  "author": {
+    "name": "Eric Mika",
+    "email": "eric@ericmika.com",
+    "url": "https://ericmika.com"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=8.0.0"
+  },
+  "bin": {
+    "mdat": "bin/cli.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "bin/*",
+    "dist/*"
+  ],
+  "keywords": [
+    "mdat",
+    "markdown",
+    "template",
+    "comments",
+    "docs-generator",
+    "docs",
+    "cli"
+  ],
+  "dependencies": {
+    "@types/mdast": "^4.0.3",
+    "@types/unist": "^3.0.2",
+    "chalk": "^5.3.0",
+    "cosmiconfig": "^9.0.0",
+    "path-type": "^5.0.0",
+    "plur": "^5.1.0",
+    "pretty-ms": "^9.0.0",
+    "remark": "^15.0.1",
+    "remark-gfm": "^4.0.0",
+    "to-vfile": "^8.0.0",
+    "type-fest": "^4.10.2",
+    "untildify": "^5.0.0",
+    "vfile": "^6.0.1",
+    "yargs": "^17.7.2",
+    "zod": "^3.22.4",
+    "remark-mdat": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.14",
+    "@types/yargs": "^17.0.32",
+    "execa": "^8.0.1",
+    "nanoid": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "pnpm run test",
+    "mdat": "../mdat-readme/bin/cli.js --config ../../mdat.config.ts",
+    "pretest": "pnpm run build",
+    "test": "vitest"
+  }
+}

package/readme.md

@@ -0,0 +1,354 @@
+<!--+ Warning: Content in HTML comment blocks generated by mdat on 2024-02-08 +-->
+
+<!-- header -->
+
+# mdat
+
+[![NPM Package](https://img.shields.io/npm/v/mdat.svg)](https://npmjs.com/package/mdat)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**CLI tool and library for using comments as content templates in Markdown files.**
+
+<!-- /header -->
+
+> \[!NOTE]\
+> **Please see the [Mdat Monorepo readme](http://github.com/kitschpatrol/mdat) for additional context.**
+
+<!-- table-of-contents -->
+
+## Table of contents
+
+- [Overview](#overview)
+- [Getting started](#getting-started)
+  - [Dependencies](#dependencies)
+  - [Installation](#installation)
+- [Usage](#usage)
+  - [CLI](#cli)
+  - [API](#api)
+  - [Configuration](#configuration)
+- [Creating custom rules](#creating-custom-rules)
+- [Maintainers](#maintainers)
+- [Acknowledgements](#acknowledgements)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- /table-of-contents -->
+
+## Overview
+
+This is a CLI tool and library implementing the Markdown Autophagic Template (mdat) system, which makes it easy to automate the replacement of placeholder comments in Markdown documents with dynamic content from a variety of sources. `mdat` also validates the structure and content of the Markdown document based on constraints specified in the expansion rules.
+
+A trivial example...
+
+Given placeholder comments in a Markdown file like this:
+
+`some-file.md`
+
+```md
+<!-- title -->
+```
+
+Run your file through the tool:
+
+```sh
+mdat some-file.md
+```
+
+To turn it into:
+
+`some-file.md`
+
+```md
+<!-- title -->
+
+# mdat
+
+<!-- /title -->
+```
+
+In this case, according to a set of rules defined in an external configuration file, `<!-- title -->` was replaced with date from `package.json`. The rule system behind these expansions is simple to define and readily extensible beyond the trivial example above.
+
+The `mdat` CLI and library package sits between the lower-level \[`remark-mdat`] remark plugin, and the higher-level \[`mdat-readme`] package. `mdat` offers flexibility, but if you're just looking to expand some placeholders in your readme files then [`mdat-readme`](../mdat-readme) is the place to start.
+
+## Getting started
+
+### Dependencies
+
+The `mdat` CLI tool requires Node 16+. The exported APIs for expanding Markdown text and documents are ESM-only and share the Node 16+ requirement. `mdat` is implemented in TypeScript and bundles a complete set of type definitions.
+
+### Installation
+
+Install locally to access the CLI commands in a single project or to import the provided APIs:
+
+```sh
+npm install remark-mdat
+```
+
+Or, install globally for access across your system:
+
+```sh
+npm install --global remark-mdat
+```
+
+## Usage
+
+> \[!WARNING]\
+> **The `mdat` CLI tool directly manipulates the contents of readme files, in close (and perhaps dangerous) proximity to your painstakingly crafted words.**
+>
+> Please make sure any text you care about is committed before running `mdat`, and never directly modify content inside of the comment expansion blocks.
+>
+> Set the `--meta` flag on the command to add a warning comment to the top of your file explaining the extra caution demanded around the volatile automated sections of your readme.md.
+
+### CLI
+
+<!-- cli-help -->
+
+#### Command: `mdat`
+
+Note: `expand` is the default and only command at the moment.
+
+This section lists top-level commands for `mdat`.
+
+If no command is provided, `mdat expand` is run by default.
+
+Usage:
+
+```txt
+mdat [command] [options]
+```
+
+| Command  | Argument                | Description                                                         |
+| -------- | ----------------------- | ------------------------------------------------------------------- |
+| `expand` | `<files..>` `[options]` | Expand comment placeholders in Markdown files. _(Default command.)_ |
+
+_See the sections below for more information on each subcommand._
+
+#### Subcommand: `mdat expand`
+
+Expand comment placeholders in Markdown files.
+
+Usage:
+
+```txt
+mdat expand <files..> [options]
+```
+
+| Positional Argument | Description                                                                | Type     |
+| ------------------- | -------------------------------------------------------------------------- | -------- |
+| `files`             | Markdown file(s) with `mdat` placeholder comments to expand. _(Required.)_ | `string` |
+
+| Option      | Alias | Description                                                                                                                                                                                                   | Type      | Default                                                                       |
+| ----------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `--config`  |       | Path(s) to files containing mdat configs.                                                                                                                                                                     | `array`   | Configuration is loaded if found from the usual places, or defaults are used. |
+| `--rules`   | `-r`  | Path(s) to files containing `mdat` comment expansion rules.                                                                                                                                                   | `array`   |                                                                               |
+| `--output`  | `-o`  | Output file directory.                                                                                                                                                                                        | `string`  | Same directory as input file.                                                 |
+| `--name`    | `-n`  | Output file name.                                                                                                                                                                                             | `string`  | Same name as input file. Overwrites the input file.                           |
+| `--print`   |       | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.                                                                                                   | `boolean` | `false`                                                                       |
+| `--prefix`  |       | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-`mdat` comments in your Markdown file, or if you're willing to trade some verbosity for safety. | `string`  |                                                                               |
+| `--meta`    | `-m`  | Embed an extra comment at the top of the generated Markdown noting the date of generation and warning editors that certain sections of the document have been generated dynamically.                          | `boolean` | `false`                                                                       |
+| `--check`   | `-c`  | Check the input files for rule violations without expanding them. Identifies things like missing comment placeholders and incorrect placeholder ordering.                                                     | `boolean` | `false`                                                                       |
+| `--verbose` |       | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.                                                                                 | `boolean` | `false`                                                                       |
+| `--help`    | `-h`  | Show help                                                                                                                                                                                                     | `boolean` |                                                                               |
+| `--version` | `-v`  | Show version number                                                                                                                                                                                           | `boolean` |                                                                               |
+
+<!-- /cli-help -->
+
+<!-- cli-help-note -->
+
+_Meta note: The entire section above was generated automatically by the [`<!-- cli-help -->`](../mdat-readme/src/lib/rules/cli-help/index.ts) mdat expansion rule provided in `mdat-readme`. It dynamically parses the output from `mdat --help` into a markdown table, recursively calling `--help` on subcommands to build a Markdown representation of the help output._
+
+<!-- /cli-help-note -->
+
+#### Examples
+
+##### Basic
+
+Expand comments in a single Markdown file in-place:
+
+```sh
+mdat your-file.md
+```
+
+##### Multi-file
+
+Expand comments in multiple Markdown files:
+
+```sh
+mdat *.md
+```
+
+##### Custom configuration
+
+A number of option flags are exposed on the CLI. Any values set here will override both ambient configuration files and any configuration file referenced passed as options:
+
+```sh
+mdat  --prefix 'mm-
+```
+
+##### Custom configuration file
+
+```sh
+mdat  --config 'custom-config.ts"
+```
+
+##### Rule sets
+
+```sh
+mdat --rules 'rules.ts' 'more-rules.js' 'yet-more-rules.json'
+```
+
+### API
+
+`mdat` exports a collection of functions to abstract the process of expanding placeholder comments into a single call. Type aliases are also provided.
+
+Highlights include:
+
+#### Expand String
+
+```ts
+function expandString(markdown: string, config?: ExpandConfig, rules?: ExpandRules): Promise<VFile>
+```
+
+Takes a string of Markdown and returns. Note that the returned object is a [VFile](https://github.com/vfile), which includes both the post-conversion Markdown content and additional metadata about the conversion.
+
+To get the Markdown content, simply call `.toString()` on the returned VFile object.
+
+#### Expand File
+
+```ts
+function expandFile(
+  file: string,
+  name?: string,
+  output?: string,
+  config?: ExpandConfig,
+  rules?: ExpandRules,
+): Promise<VFile>
+```
+
+Similar to `expandString()`, but takes a file path and handles setting an optional destination path and file name.
+
+It's up to the caller to actually save the returned VFile object. The [to-vfile](https://www.npmjs.com/package/to-vfile) library can make this particularly painless:
+
+```ts
+import { expandFile } from 'mdat'
+import { write } from 'to-vfile'
+
+const file = await expandFiles(...)
+await write(file)
+```
+
+#### Expand Files
+
+```ts
+function expandFiles(
+  files: string[],
+  name?: string,
+  output?: string,
+  config?: ExpandConfig,
+  rules?: ExpandRules,
+): Promise<VFile[]>
+```
+
+Like `expandFile()`, but accepts an array of inputs. If an output name is specified, the output files are suffixed with a number to prevent name collisions.
+
+#### Load Config
+
+```ts
+function loadConfig<T extends Partial<Options>>(options?: {
+  additionalConfig?: Array<T | string> | T | string | undefined
+  additionalRules?: Array<Rules | string> | Rules | string | undefined
+  configExtensionSchema?: z.ZodObject<any>
+  searchFrom?: string
+}): Promise<T>
+```
+
+This is provided for more advanced use cases. It assists in discovering and loading ambient configuration in your project (e.g. fields in your package.json, or dedicated `mdat` config files). It also dynamically loads, validates, and merges additional `mdat` configuration and rule files into a final `ExpandConfig` object ready to be passed into the [`remark-mdat`](../remark-mdat/readme.md) plugin or one of the API functions like `expandFile()`.
+
+The function is generic to accommodate extensions to the configuration type in derivative projects. ([`mdat-readme`]() uses this approach.)
+
+#### Examples
+
+### Configuration
+
+Expansion rules and certain aspects of global configuration are defined in configuration files which may be discovered automatically by `mdat`, or explicitly provided via command line options or library function arguments as shown above.
+
+`mdat` implements configuration loading via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig), which means a variety of configuration [locations](https://github.com/cosmiconfig/cosmiconfig?tab=readme-ov-file#searchplaces) and file formats are supported. Configuration may be defined directly in your package.json, or in addition to stand-alone TypeScript files, JavaScript files, YAML, JSON, etc.
+
+TypeScript or JavaScript with JSDoc annotations are recommended for the most flexibility and ease of implementing more advanced rules.
+
+`mdat` also allows arbitrary JSON files to be loaded as rule sets, flattening them so any value may be accessed by using a dot-notation key path as a comment keyword.
+
+#### Configuration file format
+
+The `mdat` configuration file is a record object allowing you to customize aspects of the comment expansion process, and also optionally define expansion rules as well under the `rules` key:
+
+```ts
+type MdatConfig = {
+  addMetaComment?: boolean
+  closingPrefix?: string
+  keywordPrefix?: string
+  metaCommentIdentifier?: string
+  rules?: Rules
+}
+```
+
+A valid configuration file default-exports an object conforming to the above type.
+
+The configuration file may be located in any location supported by [cosmicconfig](https://github.com/cosmiconfig/cosmiconfig?tab=readme-ov-file#searchplaces). I use a `mdat.config.ts` file in the root of my projects.
+
+#### Rule file format
+
+Rules may also be defined in separate files that default-export a record of rules. The record keys become the keywords used to reference a rule from your comments in Markdown.
+
+```ts
+type Rules = Record<string, Rule>
+
+type Rule =
+  | string
+  | ((options: JsonValue, tree: Root) => Promise<string> | string)
+  | Rule[]
+  | {
+      content: string | Rule[] | ((options: JsonValue, tree: Root) => Promise<string> | string)
+      applicationOrder?: number | undefined
+      order?: number | undefined
+      required?: boolean | undefined
+    }
+```
+
+This is a bit complex, but it's indented to make defining simple rules simple, while still accommodating more demanding use cases.
+
+Some notes on the type:
+
+- Simple rules can be defined directly on the key, either as strings to replace the comment placeholder, or as sync or async functions returning a string.
+
+- If you need more advanced rules, or wish to define conditions for the validation process, you break the top-level keyword key's value out into an object, where a `content` key on the object is responsible for returning the replacement string, and additional fields are available to define validation constraints.
+
+- Note that `content` can itself take an array of Rule objects, which is useful for creating "compound" rules that combine several others into a single comment keyword.
+
+Since it's a record, multiple rules may be combined in single rules file.
+
+If multiple configuration and rule files are loaded, they are merged. CLI options take precedence over ambient configuration discovered by cosmicconfig, and where multiple configuration or rule files are provided, with the "last" rule of a particular key takes precedence.
+
+## Creating custom rules
+
+See the [Examples section](../remark-mdat/readme.md#examples) of the `remark-mdat` readme, or take a look at the implementation of the [rules bundled with `mdat-readme`](../mdat-readme/src/lib/rules/) for more complex examples.
+
+## Maintainers
+
+[@kitschpatrol](https://github.com/kitschpatrol)
+
+## Acknowledgements
+
+Please see the [monorepo readme](../../readme.md#acknowledgments).
+
+<!-- footer -->
+
+## Contributing
+
+[Issues](https://github.com/kitschpatrol/mdat/issues) and pull requests are welcome.
+
+## License
+
+[MIT](license.txt) © Eric Mika
+
+<!-- /footer -->