mdat 0.7.1 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/bin/cli.js +81 -80
  2. package/dist/index.js +56 -55
  3. package/package.json +20 -19
  4. package/readme.md +104 -102
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mdat",
3
- "version": "0.7.1",
3
+ "version": "0.7.3",
4
4
  "type": "module",
5
5
  "description": "CLI tool and library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.",
6
6
  "repository": {
@@ -19,8 +19,8 @@
19
19
  },
20
20
  "license": "MIT",
21
21
  "engines": {
22
- "node": ">=18.0.0",
23
- "pnpm": ">=8.0.0"
22
+ "node": "^18.19.0 || >=20.5.0",
23
+ "pnpm": ">=9.0.0"
24
24
  },
25
25
  "bin": {
26
26
  "mdat": "bin/cli.js"
@@ -45,22 +45,22 @@
45
45
  ],
46
46
  "dependencies": {
47
47
  "@clack/prompts": "^0.7.0",
48
- "@kitschpatrol/tldraw-cli": "^4.5.4",
48
+ "@kitschpatrol/tldraw-cli": "^4.6.11",
49
49
  "@types/mdast": "^4.0.4",
50
- "@types/node": "^20.14.2",
50
+ "@types/node": "18.19.0",
51
51
  "@types/unist": "^3.0.2",
52
52
  "@types/which": "^3.0.4",
53
- "@types/yargs": "^17.0.32",
53
+ "@types/yargs": "^17.0.33",
54
54
  "cosmiconfig": "^9.0.0",
55
55
  "cosmiconfig-typescript-loader": "^5.0.0",
56
- "execa": "^9.2.0",
57
- "globby": "^14.0.1",
56
+ "execa": "^9.3.0",
57
+ "globby": "^14.0.2",
58
58
  "read-pkg": "^9.0.1",
59
59
  "which": "^4.0.0"
60
60
  },
61
61
  "devDependencies": {
62
- "@kitschpatrol/shared-config": "^4.7.1",
63
- "bumpp": "^9.4.1",
62
+ "@kitschpatrol/shared-config": "^4.7.2",
63
+ "bumpp": "^9.5.1",
64
64
  "chalk": "^5.3.0",
65
65
  "chevrotain": "^11.0.3",
66
66
  "find-up": "^7.0.0",
@@ -68,20 +68,21 @@
68
68
  "mdast-util-toc": "^7.1.0",
69
69
  "nanoid": "^5.0.7",
70
70
  "package-up": "^5.0.0",
71
- "path-type": "^5.0.0",
71
+ "path-type": "^6.0.0",
72
72
  "pkg-dir": "^8.0.0",
73
73
  "plur": "^5.1.0",
74
- "pretty-ms": "^9.0.0",
74
+ "pretty-ms": "^9.1.0",
75
75
  "remark": "^15.0.1",
76
76
  "remark-gfm": "^4.0.0",
77
- "remark-mdat": "^0.7.0",
77
+ "remark-mdat": "^0.7.1",
78
+ "rimraf": "^6.0.1",
78
79
  "to-vfile": "^8.0.0",
79
- "tsup": "^8.1.0",
80
- "type-fest": "^4.20.0",
81
- "typescript": "^5.4.5",
80
+ "tsup": "^8.2.4",
81
+ "type-fest": "^4.24.0",
82
+ "typescript": "^5.5.4",
82
83
  "untildify": "^5.0.0",
83
- "vfile": "^6.0.1",
84
- "vitest": "^1.6.0",
84
+ "vfile": "^6.0.2",
85
+ "vitest": "^2.0.5",
85
86
  "yargs": "^17.7.2",
86
87
  "zod": "^3.23.8"
87
88
  },
@@ -90,7 +91,7 @@
90
91
  },
91
92
  "scripts": {
92
93
  "build": "tsup && tsc -p tsconfig.build.lib.json",
93
- "clean": "git clean -fdX && rm ./pnpm-lock.yaml",
94
+ "clean": "rimraf ./pnpm-lock.yaml && git clean -fdX",
94
95
  "dev": "pnpm run test",
95
96
  "fix": "pnpm shared-config --fix",
96
97
  "lint": "pnpm shared-config --lint",
package/readme.md CHANGED
@@ -50,7 +50,7 @@
50
50
 
51
51
  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. The `mdat` command can also validate the structure and content of the Markdown document based on constraints specified in the expansion rules, and bundles numerous convenient expansion rules for working with `readme.md` files under the `mdat readme` subcommand.
52
52
 
53
- <!-- tldraw src: "./assets/mdat-flow.tldr" -->
53
+ <!-- tldraw src: "assets/mdat-flow.tldr" -->
54
54
 
55
55
  <picture>
56
56
  <source media="(prefers-color-scheme: dark)" srcset="assets/mdat-flow-63a3366c-dark.svg">
@@ -88,13 +88,13 @@ To turn it into:
88
88
  <!-- /title -->
89
89
  ```
90
90
 
91
- 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.
91
+ In this case, according to a set of rules defined in an external configuration file, `<!-- title -->` was replaced with data from `package.json`. The rule system behind these expansions is simple to define and readily extensible beyond the trivial example above.
92
92
 
93
93
  ## Getting started
94
94
 
95
95
  ### Dependencies
96
96
 
97
- The `mdat` CLI tool requires Node 18+. The exported APIs for expanding Markdown text and documents are ESM-only and share the Node 18+ requirement. `mdat` is implemented in TypeScript and bundles a complete set of type definitions.
97
+ The `mdat` CLI tool and API requires Node 18+ (specifically `^18.19.0 || >=20.5.0`). The exported APIs for expanding Markdown text and documents are. `mdat` is implemented in TypeScript and bundles a complete set of type definitions.
98
98
 
99
99
  ### Installation
100
100
 
@@ -190,7 +190,7 @@ As [noted below](#similar-projects), there are several similar projects out ther
190
190
  }
191
191
  ```
192
192
 
193
- This scales all the way up to some of the [more](./src/lib/readme/rules/table-of-contents.ts) [elaborate](./src/lib/readme/rules/cli-help) rules found in the `mdat readme` subcommand.
193
+ This scales all the way up to some of the [more](src/lib/readme/rules/table-of-contents.ts) [elaborate](src/lib/readme/rules/cli-help) rules found in the `mdat readme` subcommand.
194
194
 
195
195
  You can also treat any JSON file as a rule set. MDAT will flatten it to allow any dot-notated key path to become a placeholder comment keyword.
196
196
 
@@ -206,7 +206,7 @@ As [noted below](#similar-projects), there are several similar projects out ther
206
206
 
207
207
  It's easy to create "compound" expansion rules that encapsulate a number of other individual rules into a single Markdown comment to keep the quantity of template comments in check.
208
208
 
209
- See the [`<!-- header -->`](./src/lib/readme/rules/header.ts) rule in the `mdat readme` subcommand for an example.
209
+ See the [`<!-- header -->`](src/lib/readme/rules/header.ts) rule in the `mdat readme` subcommand for an example.
210
210
 
211
211
  8. **Single-command readme workflow**
212
212
 
@@ -264,18 +264,18 @@ mdat expand <files..> [options]
264
264
  | ------------------- | -------------------------------------------------------------- | -------- |
265
265
  | `files` | Markdown file(s) with MDAT placeholder comments. _(Required.)_ | `string` |
266
266
 
267
- | Option | Alias | Description | Type | Default |
268
- | ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
269
- | `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
270
- | `--rules` | `-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
271
- | `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
272
- | `--name` | `-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
273
- | `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
274
- | `--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` | |
275
- | `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
276
- | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
277
- | `--help` | `-h` | Show help | `boolean` | |
278
- | `--version` | `-v` | Show version number | `boolean` | |
267
+ | Option | Description | Type | Default |
268
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
269
+ | `--config` | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
270
+ | `--rules`<br>`-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
271
+ | `--output`<br>`-o` | Output file directory. | `string` | Same directory as input file. |
272
+ | `--name`<br>`-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
273
+ | `--meta`<br>`-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
274
+ | `--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` | |
275
+ | `--print` | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
276
+ | `--verbose` | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
277
+ | `--help`<br>`-h` | Show help | `boolean` | |
278
+ | `--version`<br>`-v` | Show version number | `boolean` | |
279
279
 
280
280
  #### Subcommand: `mdat check`
281
281
 
@@ -291,15 +291,15 @@ mdat check <files..> [options]
291
291
  | ------------------- | -------------------------------------------------------------- | -------- |
292
292
  | `files` | Markdown file(s) with MDAT placeholder comments. _(Required.)_ | `string` |
293
293
 
294
- | Option | Alias | Description | Type | Default |
295
- | ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
296
- | `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
297
- | `--rules` | `-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
298
- | `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
299
- | `--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` | |
300
- | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
301
- | `--help` | `-h` | Show help | `boolean` | |
302
- | `--version` | `-v` | Show version number | `boolean` | |
294
+ | Option | Description | Type | Default |
295
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
296
+ | `--config` | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
297
+ | `--rules`<br>`-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
298
+ | `--meta`<br>`-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
299
+ | `--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` | |
300
+ | `--verbose` | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
301
+ | `--help`<br>`-h` | Show help | `boolean` | |
302
+ | `--version`<br>`-v` | Show version number | `boolean` | |
303
303
 
304
304
  #### Subcommand: `mdat collapse`
305
305
 
@@ -315,16 +315,16 @@ mdat collapse <files..> [options]
315
315
  | ------------------- | -------------------------------------------------------------- | -------- |
316
316
  | `files` | Markdown file(s) with MDAT placeholder comments. _(Required.)_ | `string` |
317
317
 
318
- | Option | Alias | Description | Type | Default |
319
- | ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
320
- | `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
321
- | `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
322
- | `--name` | `-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
323
- | `--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` | |
324
- | `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
325
- | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
326
- | `--help` | `-h` | Show help | `boolean` | |
327
- | `--version` | `-v` | Show version number | `boolean` | |
318
+ | Option | Description | Type | Default |
319
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
320
+ | `--config` | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
321
+ | `--output`<br>`-o` | Output file directory. | `string` | Same directory as input file. |
322
+ | `--name`<br>`-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
323
+ | `--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` | |
324
+ | `--print` | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
325
+ | `--verbose` | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
326
+ | `--help`<br>`-h` | Show help | `boolean` | |
327
+ | `--version`<br>`-v` | Show version number | `boolean` | |
328
328
 
329
329
  #### Subcommand: `mdat readme`
330
330
 
@@ -359,24 +359,24 @@ Usage:
359
359
  mdat readme expand [files..] [options]
360
360
  ```
361
361
 
362
- | Positional Argument | Description | Type |
363
- | ------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
364
- | `files` | Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. _(Optional.)_ | `string` |
365
-
366
- | Option | Alias | Description | Type | Default |
367
- | ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
368
- | `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
369
- | `--rules` | `-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
370
- | `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
371
- | `--name` | `-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
372
- | `--package` | | Path to the package.json file to use to populate the readme. | `string` | The closest package.json file is used by default. |
373
- | `--assets` | | Path to find and save readme-related assets. | `string` | `./assets` |
374
- | `--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` | |
375
- | `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
376
- | `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
377
- | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
378
- | `--help` | `-h` | Show help | `boolean` | |
379
- | `--version` | `-v` | Show version number | `boolean` | |
362
+ | Positional Argument | Description | Type |
363
+ | ------------------- | --------------------------------------------------------------------------------------------------- | -------- |
364
+ | `files` | Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. | `string` |
365
+
366
+ | Option | Description | Type | Default |
367
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
368
+ | `--config` | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
369
+ | `--rules`<br>`-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
370
+ | `--output`<br>`-o` | Output file directory. | `string` | Same directory as input file. |
371
+ | `--name`<br>`-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
372
+ | `--package` | Path to the package.json file to use to populate the readme. | `string` | The closest package.json file is used by default. |
373
+ | `--assets` | Path to find and save readme-related assets. | `string` | `./assets` |
374
+ | `--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` | |
375
+ | `--meta`<br>`-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
376
+ | `--print` | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
377
+ | `--verbose` | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
378
+ | `--help`<br>`-h` | Show help | `boolean` | |
379
+ | `--version`<br>`-v` | Show version number | `boolean` | |
380
380
 
381
381
  #### Subcommand: `mdat readme check`
382
382
 
@@ -388,21 +388,21 @@ Usage:
388
388
  mdat readme check [files..] [options]
389
389
  ```
390
390
 
391
- | Positional Argument | Description | Type |
392
- | ------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
393
- | `files` | Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. _(Optional.)_ | `string` |
394
-
395
- | Option | Alias | Description | Type | Default |
396
- | ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
397
- | `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
398
- | `--rules` | `-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
399
- | `--package` | | Path to the package.json file to use to populate the readme. | `string` | The closest package.json file is used by default. |
400
- | `--assets` | | Path to find and save readme-related assets. | `string` | `./assets` |
401
- | `--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` | |
402
- | `--meta` | `-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
403
- | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
404
- | `--help` | `-h` | Show help | `boolean` | |
405
- | `--version` | `-v` | Show version number | `boolean` | |
391
+ | Positional Argument | Description | Type |
392
+ | ------------------- | --------------------------------------------------------------------------------------------------- | -------- |
393
+ | `files` | Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. | `string` |
394
+
395
+ | Option | Description | Type | Default |
396
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
397
+ | `--config` | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
398
+ | `--rules`<br>`-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
399
+ | `--package` | Path to the package.json file to use to populate the readme. | `string` | The closest package.json file is used by default. |
400
+ | `--assets` | Path to find and save readme-related assets. | `string` | `./assets` |
401
+ | `--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` | |
402
+ | `--meta`<br>`-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
403
+ | `--verbose` | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
404
+ | `--help`<br>`-h` | Show help | `boolean` | |
405
+ | `--version`<br>`-v` | Show version number | `boolean` | |
406
406
 
407
407
  #### Subcommand: `mdat readme collapse`
408
408
 
@@ -414,20 +414,20 @@ Usage:
414
414
  mdat readme collapse [files..] [options]
415
415
  ```
416
416
 
417
- | Positional Argument | Description | Type |
418
- | ------------------- | ----------------------------------------------------------------------------------------------------------------- | -------- |
419
- | `files` | Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. _(Optional.)_ | `string` |
420
-
421
- | Option | Alias | Description | Type | Default |
422
- | ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
423
- | `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
424
- | `--name` | `-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
425
- | `--print` | | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
426
- | `--config` | | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
427
- | `--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` | |
428
- | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
429
- | `--help` | `-h` | Show help | `boolean` | |
430
- | `--version` | `-v` | Show version number | `boolean` | |
417
+ | Positional Argument | Description | Type |
418
+ | ------------------- | --------------------------------------------------------------------------------------------------- | -------- |
419
+ | `files` | Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. | `string` |
420
+
421
+ | Option | Description | Type | Default |
422
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
423
+ | `--output`<br>`-o` | Output file directory. | `string` | Same directory as input file. |
424
+ | `--name`<br>`-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
425
+ | `--print` | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
426
+ | `--config` | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
427
+ | `--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` | |
428
+ | `--verbose` | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
429
+ | `--help`<br>`-h` | Show help | `boolean` | |
430
+ | `--version`<br>`-v` | Show version number | `boolean` | |
431
431
 
432
432
  #### Subcommand: `mdat readme init`
433
433
 
@@ -439,21 +439,21 @@ Usage:
439
439
  mdat readme init [options]
440
440
  ```
441
441
 
442
- | Option | Alias | Description | Type | Default |
443
- | --------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------- |
444
- | `--interactive` | `-i` | Run the guided interactive `init` process. Set explicitly to `false` to use default values and skip the prompt. | `boolean` | `true` |
445
- | `--overwrite` | | Replace an existing readme file if one is found. | `boolean` | `false`, if an existing readme is found, don't touch it. |
446
- | `--output` | `-o` | Output file directory. | `string` | Same directory as input file. |
447
- | `--expand` | `-e` | Automatically run `mdat readme` immediately after creating the readme template. | `boolean` | `true` |
448
- | `--template` | `-t` | Specify a template to use for the new readme. | `string` | "MDAT Readme" |
449
- | `--compound` | `-c` | Use compound comment version of the template to replace several individual comment placeholders where possible. This combines things like `<!-- title -->`, `<!-- badges -->`, etc. in a single `<!-- header -->` comment. It's less clutter when you're editing, but it's also less explicit. The final readme.md output is identical. | `boolean` | `true` |
450
- | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
451
- | `--help` | `-h` | Show help | `boolean` | |
452
- | `--version` | `-v` | Show version number | `boolean` | |
442
+ | Option | Description | Type | Default |
443
+ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------- |
444
+ | `--interactive`<br>`-i` | Run the guided interactive `init` process. Set explicitly to `false` to use default values and skip the prompt. | `boolean` | `true` |
445
+ | `--overwrite` | Replace an existing readme file if one is found. | `boolean` | `false`, if an existing readme is found, don't touch it. |
446
+ | `--output`<br>`-o` | Output file directory. | `string` | Same directory as input file. |
447
+ | `--expand`<br>`-e` | Automatically run `mdat readme` immediately after creating the readme template. | `boolean` | `true` |
448
+ | `--template`<br>`-t` | Specify a template to use for the new readme. | `"MDAT Readme"` `"Standard Readme Basic"` `"Standard Readme Full"` | `"MDAT Readme"` |
449
+ | `--compound`<br>`-c` | Use compound comment version of the template to replace several individual comment placeholders where possible. This combines things like `<!-- title -->`, `<!-- badges -->`, etc. in a single `<!-- header -->` comment. It's less clutter when you're editing, but it's also less explicit. The final readme.md output is identical. | `boolean` | `true` |
450
+ | `--verbose` | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
451
+ | `--help`<br>`-h` | Show help | `boolean` | |
452
+ | `--version`<br>`-v` | Show version number | `boolean` | |
453
453
 
454
454
  <!-- /cli-help -->
455
455
 
456
- _Meta note: The entire section above was generated automatically by the [`<!-- cli-help -->`](./src/lib/readme/rules/cli-help/index.ts) mdat expansion rule provided in `mdat readme` subcommand. It dynamically parses the output from `mdat --help` into a Markdown table, recursively calling `--help` on subcommands to build a tidy representation of the help output._
456
+ _Meta note: The entire section above was generated automatically by the [`<!-- cli-help -->`](src/lib/readme/rules/cli-help/index.ts) mdat expansion rule provided in `mdat readme` subcommand. It dynamically parses the output from `mdat --help` into a Markdown table, recursively calling `--help` on subcommands to build a tidy representation of the help output._
457
457
 
458
458
  #### Examples
459
459
 
@@ -587,7 +587,7 @@ function loadConfig(options?: {
587
587
  }): Promise<ConfigLoaded> // returns a single merged config object
588
588
  ```
589
589
 
590
- 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 `ConfigLoaded` object ready to be passed into the [`remark-mdat`](https://github.com/kitschpatorl/remark-mdat) plugin or one of the API functions like `expandFile()`.
590
+ 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 `ConfigLoaded` object ready to be passed into the [`remark-mdat`](https://github.com/kitschpatrol/remark-mdat) plugin or one of the API functions like `expandFile()`.
591
591
 
592
592
  #### Examples
593
593
 
@@ -658,7 +658,7 @@ If multiple configuration and rule files are loaded, they are merged. CLI option
658
658
 
659
659
  The underlying rule expansion system is flexible and easy to extend.
660
660
 
661
- See the [Examples section](https://github.com/kitschpatrol/remark-mdat/readme.md#examples) of the `remark-mdat` readme, or take a look at the implementation of the [rules provided through the `mdat readme` subcommand](./src/lib/readme/rules/) for more complex examples.
661
+ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples) of the `remark-mdat` readme, or take a look at the implementation of the [rules provided through the `mdat readme` subcommand](src/lib/readme/rules) for more complex examples.
662
662
 
663
663
  ### The `mdat readme` subcommand
664
664
 
@@ -698,7 +698,7 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat/readme.md
698
698
 
699
699
  Documents the project's license, based on the `license` field from `package.json`.
700
700
 
701
- - ###### `<!-- code -->`
701
+ - ###### `<!-- code { file: "./file.ts" } -->`
702
702
 
703
703
  A quick way to embed a code block from elsewhere in your repository. Useful for examples.
704
704
 
@@ -708,11 +708,11 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat/readme.md
708
708
 
709
709
  Currently, the rule can only parse help output in the format provided by [Yargs](https://yargs.js.org)- and [Meow](https://github.com/sindresorhus/meow)-based tools. If parsing fails, the rule will fall back to show the raw help output in a regular code block.
710
710
 
711
- ([Parsing help output](https://github.com/kitschpatrol/mdat/tree/main/src/lib/readme/rules/cli-help/utilities/parsers) is a bit tricky. The [jc](https://github.com/kellyjonbrazil/jc) project is a heroic collection of output parsers, but does not currently implement help output parsing. It might be interesting to try to contribute mdat's help parsing implementations to jc.)
711
+ ([Parsing help output](src/lib/readme/rules/cli-help/utilities/parsers) is a bit tricky. The [jc](https://github.com/kellyjonbrazil/jc) project is a heroic collection of output parsers, but does not currently implement help output parsing. It might be interesting to try to contribute mdat's help parsing implementations to jc.)
712
712
 
713
713
  This rule is also aliased under the `<!-- cli -->` keyword.
714
714
 
715
- - ###### `<!-- tldraw -->`
715
+ - ###### `<!-- tldraw { src: "./sketch.tldr" } -->`
716
716
 
717
717
  Allows embedding [tldraw](https://www.tldraw.com) files in your readme. Accepts either a path to a local `.tldr` file, or remote tldraw URLs.
718
718
 
@@ -789,6 +789,8 @@ This has been done several times before:
789
789
  - Titus Wormer's [mdast-zone](https://github.com/syntax-tree/mdast-zone)\
790
790
  Allows comments to be used as ranges or markers in Markdown files. Similar tree parsing and walking strategy to MDAT. Mdast-zone uses different syntax for arguments, and requires both opening and closing tags to be present for expansion to occur.
791
791
 
792
+ - Jason Dent's [inject-markdown](https://github.com/streetsidesoftware/inject-markdown)\\
793
+
792
794
  - lillallol's [md-in-place](https://www.npmjs.com/package/md-in-place)
793
795
 
794
796
  ### Implementation notes
@@ -800,7 +802,7 @@ This project was split from a monorepo containing both `mdat` and `remark-mdat`
800
802
  Additional rules:
801
803
 
802
804
  - Support embedding code documentation snippets via [typedoc](https://github.com/TypeStrong/typedoc) + [typedoc-plugin-markdown](https://github.com/tgreyuk/typedoc-plugin-markdown).
803
- - Support line ranges i the `<!-- code -->` rule.
805
+ - Support line ranges in the `<!-- code -->` rule.
804
806
 
805
807
  Improved documentation:
806
808
 
@@ -817,7 +819,7 @@ Recommended workflow integration approach:
817
819
 
818
820
  ## Acknowledgments
819
821
 
820
- - The [unified](https://unifiedjs.com), [remark](https://remark.js.org), and [unist](https://github.com/syntax-tree/unist) / [mdast](https://github.com/syntax-tree/mdast) ecosystem is powerful and well-architected. MDAT relies on it to do the the heavy lifting in of parsing, transforming, and restoring the Markdown to string form.
822
+ - The [unified](https://unifiedjs.com), [remark](https://remark.js.org), and [unist](https://github.com/syntax-tree/unist) / [mdast](https://github.com/syntax-tree/mdast) ecosystem is powerful and well-architected. MDAT relies on it to do the the heavy lifting of parsing, transforming, and restoring the Markdown to string form.
821
823
 
822
824
  - Richard Litt's [Standard Readme](https://github.com/RichardLitt/standard-readme) specification inspired some of the templates available in `mdat readme init`.
823
825