mdat 2.0.0 → 2.1.0

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 (6) hide show
  1. package/dist/bin/cli.js +211 -119
  2. package/dist/lib/index.d.ts +44 -17
  3. package/dist/lib/index.js +222 -113
  4. package/package.json +11 -6
  5. package/readme.md +90 -16
  6. package/dist/.DS_Store +0 -0
package/readme.md CHANGED
@@ -1,5 +1,3 @@
1
- <!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->
2
-
3
1
  <!-- title -->
4
2
 
5
3
  # mdat
@@ -10,6 +8,7 @@
10
8
 
11
9
  [![NPM Package mdat](https://img.shields.io/npm/v/mdat.svg)](https://npmjs.com/package/mdat)
12
10
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11
+ [![CI](https://github.com/kitschpatrol/mdat/actions/workflows/ci.yml/badge.svg)](https://github.com/kitschpatrol/mdat/actions/workflows/ci.yml)
13
12
 
14
13
  <!-- /badges -->
15
14
 
@@ -229,7 +228,8 @@ mdat [command] [files..] [options]
229
228
  | ---------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
230
229
  | `expand` | `[files..]` `[options]` | Expand MDAT placeholder comments. If no files are provided, the closest readme.md is expanded. _(Default command.)_ |
231
230
  | `collapse` | `[files..]` `[options]` | Collapse MDAT placeholder comments. If no files are provided, the closest readme.md is collapsed. |
232
- | `check` | `[files..]` `[options]` | Check if MDAT placeholder comments are up to date. Exits with code 1 if any files are out of sync. |
231
+ | `strip` | `[files..]` `[options]` | Strip MDAT comments while preserving expanded content. If no files are provided, the closest readme.md is stripped. |
232
+ | `check` | `[files..]` `[options]` | Check if MDAT placeholder comments are up to date. Exits with code 1 if any files have stale or unexpanded content. |
233
233
  | `create` | `[options]` | Create a new Markdown file from a template. |
234
234
 
235
235
  _See the sections below for more information on each subcommand._
@@ -283,9 +283,33 @@ mdat collapse [files..] [options]
283
283
  | `--help`<br>`-h` | Show help | `boolean` | |
284
284
  | `--version`<br>`-v` | Show version number | `boolean` | |
285
285
 
286
+ #### Subcommand: `mdat strip`
287
+
288
+ Strip MDAT comments while preserving expanded content. If no files are provided, the closest readme.md is stripped.
289
+
290
+ Usage:
291
+
292
+ ```txt
293
+ mdat strip [files..] [options]
294
+ ```
295
+
296
+ | Positional Argument | Description | Type |
297
+ | ------------------- | ----------------------------------------------------------------------------------------------------- | -------- |
298
+ | `files` | Markdown file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used. | `string` |
299
+
300
+ | Option | Description | Type | Default |
301
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------- |
302
+ | `--verbose` | Enable verbose logging. All verbose logs are prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
303
+ | `--output`<br>`-o` | Output file directory. | `string` | Same directory as input file. |
304
+ | `--name`<br>`-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
305
+ | `--print` | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
306
+ | `--format`<br>`-f` | Format the output with Prettier. Discovers Prettier config from the file path. Requires `prettier` as a peer dependency. | `boolean` | |
307
+ | `--help`<br>`-h` | Show help | `boolean` | |
308
+ | `--version`<br>`-v` | Show version number | `boolean` | |
309
+
286
310
  #### Subcommand: `mdat check`
287
311
 
288
- Check if MDAT placeholder comments are up to date. Exits with code 1 if any files are out of sync.
312
+ Check if MDAT placeholder comments are up to date. Exits with code 1 if any files have stale or unexpanded content.
289
313
 
290
314
  Usage:
291
315
 
@@ -367,6 +391,12 @@ mdat check
367
391
  mdat collapse
368
392
  ```
369
393
 
394
+ ##### Strip MDAT comments from expanded content
395
+
396
+ ```sh
397
+ mdat strip
398
+ ```
399
+
370
400
  ##### Expand and format with Prettier
371
401
 
372
402
  ```sh
@@ -421,6 +451,12 @@ Expands MDAT comments in a Markdown string. Call `.toString()` on the returned [
421
451
 
422
452
  Removes expanded content, leaving only the opening comment placeholders. Same signatures as `expand` / `expandString`.
423
453
 
454
+ #### `strip` / `stripString`
455
+
456
+ Strips all MDAT comment tags (both opening and closing) while preserving expanded content between them. Same signatures as `expand` / `expandString` (without the `config` parameter, since rules are not needed).
457
+
458
+ This is useful for producing a "clean" Markdown file that no longer depends on MDAT for future updates.
459
+
424
460
  #### `check`
425
461
 
426
462
  ```ts
@@ -578,16 +614,16 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
578
614
 
579
615
  Embeds a file's size, with optional Brotli or Gzip compressed size.
580
616
 
581
- - ##### `<!-- size-table({ files: [".gitignore", "readme.md"] }) -->`
617
+ - ##### `<!-- size-table({ files: [".gitignore", "license.txt"] }) -->`
582
618
 
583
619
  A table of files and their compressed sizes:
584
620
 
585
- <!-- size-table({ files: [".gitignore", "readme.md"] }) -->
621
+ <!-- size-table({ files: [".gitignore", "license.txt"] }) -->
586
622
 
587
- | File | Original | Gzip | Brotli |
588
- | ---------- | -------- | ------ | ------ |
589
- | .gitignore | 305 B | 245 B | 216 B |
590
- | readme.md | 18.1 kB | 6.4 kB | 5.4 kB |
623
+ | File | Original | Gzip | Brotli |
624
+ | ----------- | -------- | ----- | ------ |
625
+ | .gitignore | 305 B | 245 B | 216 B |
626
+ | license.txt | 1 kB | 659 B | 468 B |
591
627
 
592
628
  <!-- /size-table -->
593
629
 
@@ -738,9 +774,9 @@ In 2.x, arguments **must** use function-call syntax with parentheses
738
774
 
739
775
  ### New functionality
740
776
 
741
- - The new --format flag runs expanded output through Prettier with local configuration before writing.
777
+ - The new `--format` flag runs expanded output through Prettier with local configuration before writing.
742
778
  - The badges rule now detects GitHub Actions CI workflows and includes a CI status badge automatically.
743
- - Check command re-implemented as a simplified dry-run expand + diff (exits 1 if out of sync)
779
+ - Check command reimplemented as a simplified dry-run expand and diff and reporting if content is unexpanded or out of date. Respects the `--format` flag.
744
780
 
745
781
  ### Rule shape changes
746
782
 
@@ -756,14 +792,52 @@ MDAT solves this by turning HTML comments in Markdown into placeholders for dyna
756
792
 
757
793
  ### Similar projects
758
794
 
759
- - Benjamin Lupton's [projectz](https://github.com/bevry/projectz)
760
- - David Wells' [Markdown Magic](https://github.com/DavidWells/markdown-magic)
761
- - Titus Wormer's [mdast-zone](https://github.com/syntax-tree/mdast-zone)
795
+ There's quite a bit of prior art and similar explorations of this problem space:
796
+
797
+ - Benjamin Lupton's [projectz](https://github.com/bevry/projectz)\
798
+ Goes way back.
799
+
800
+ - David Wells' [Markdown Magic](https://github.com/DavidWells/markdown-magic)\
801
+ I somehow missed the existence of this one until after building out MDAT. It's very similar conceptually, and has a nice ecosystem of plugins.
802
+
803
+ - Titus Wormer's [mdast-zone](https://github.com/syntax-tree/mdast-zone)\
804
+ 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.
805
+
762
806
  - Jason Dent's [inject-markdown](https://github.com/streetsidesoftware/inject-markdown)
807
+
763
808
  - lillallol's [md-in-place](https://www.npmjs.com/package/md-in-place)
764
- - [AutoMD](https://automd.unjs.io/)
809
+
810
+ - [AutoMD](https://automd.unjs.io/)\
811
+ Extremely similar functionality to mdat. The project was initiated around the same time as MDAT, but I didn't find the project until a few years later. Ships in the night.
812
+
813
+ - Franck Abgrall's [readme-md-generator](https://github.com/kefranabg/readme-md-generator)
814
+
765
815
  - Anders Pitman's [tuplates](https://github.com/anderspitman/tuplates-py)
816
+
817
+ - VitePress' [Markdown file inclusion](https://vitepress.dev/guide/markdown#markdown-file-inclusion)
818
+
819
+ There's quite a bit of prior art and similar explorations of this problem space:
820
+
821
+ - Benjamin Lupton's [projectz](https://github.com/bevry/projectz)\
822
+ Goes way back.
823
+
824
+ - David Wells' [Markdown Magic](https://github.com/DavidWells/markdown-magic)\
825
+ I somehow missed the existence of this one until after building out MDAT. It's very similar conceptually, and has a nice ecosystem of plugins.
826
+
827
+ - Titus Wormer's [mdast-zone](https://github.com/syntax-tree/mdast-zone)\
828
+ 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.
829
+
830
+ - Jason Dent's [inject-markdown](https://github.com/streetsidesoftware/inject-markdown)
831
+
832
+ - lillallol's [md-in-place](https://www.npmjs.com/package/md-in-place)
833
+
834
+ - [AutoMD](https://automd.unjs.io/)\
835
+ Extremely similar functionality to mdat. The project was initiated around the same time as MDAT, but I didn't find the project until a few years later. Ships in the night.
836
+
766
837
  - Franck Abgrall's [readme-md-generator](https://github.com/kefranabg/readme-md-generator)
838
+
839
+ - Anders Pitman's [tuplates](https://github.com/anderspitman/tuplates-py)
840
+
767
841
  - VitePress' [Markdown file inclusion](https://vitepress.dev/guide/markdown#markdown-file-inclusion)
768
842
 
769
843
  ### Implementation notes
package/dist/.DS_Store DELETED
Binary file