@thi.ng/hiccup-markdown 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-02-27T21:43:54Z
+- **Last updated**: 2023-03-05T16:02:40Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,16 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [3.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/hiccup-markdown@3.1.0) (2023-03-05)
+
+#### 🚀 Features
+
+- add anchor ID syntax support for headings ([86ce79e](https://github.com/thi-ng/umbrella/commit/86ce79e))
+  - update parse grammar & hd parser
+  - support for `{#id}` suffixes for defining heading anchor IDs
+  - only auto-generate anchor IDs if not explicitly specified
+  - update tests
+
 # [3.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/hiccup-markdown@3.0.0) (2023-02-27)
 
 #### 🛑 Breaking changes

package/README.md

@@ -17,6 +17,7 @@ This project is part of the
     - [Code block headers](#code-block-headers)
     - [Custom blocks](#custom-blocks)
     - [Headings with anchor IDs](#headings-with-anchor-ids)
+- [Heading with anchor {#custom-id-123}](#heading-with-anchor-custom-id-123)
     - [Metadata](#metadata)
   - [Customizing tag transforms](#customizing-tag-transforms)
   - [Serializing to HTML](#serializing-to-html)
@@ -58,7 +59,7 @@ standard syntax.
 | Code blocks   | GFM style only (triple backtick prefix), w/ mandatory language hint & optional extra headers information                                   |
 | Formatting    | Nestable **bold**, _italic_, `code`, ~~strike~~, <kbd>Key</kbd> supported in paragraphs, headings, link labels, lists, blockquotes, tables |
 | Footnotes     | Supported and stored separately in parse context                                                                                           |
-| Headings      | ATX-style only (`#` line prefix), any level                                                                                                |
+| Headings      | ATX-style only (`#` line prefix), optional custom ID attrib (via `{#custom-id}` suffix), levels 1-6 then fallback to paragraph             |
 | Horiz. Rulers | Only dash supported (e.g. `---`), min 2 chars required, length retained for downstream transformations                                     |
 | HTML elements | Unsupported                                                                                                                                |
 | Images        | Alt text is required, image can be used in link labels                                                                                     |
@@ -132,23 +133,30 @@ custom blocks (in an extensible manner).
 
 #### Headings with anchor IDs
 
-The default tag transform for headlines auto-generates ID attributes using that
-headline's body and
-[slugifying](https://docs.thi.ng/umbrella/strings/functions/slugifyGH.html) it
-(Github readme compatible):
+The parser supports `{#custom-id}`-style line suffixes for headings, which are
+passed as separate `anchorID` param to the element handlers. If not specified in
+the Markdown source, the parser auto-generates this ID (with no uniqueness
+guarantee) based on
+[slugifying](https://docs.thi.ng/umbrella/strings/functions/slugifyGH.html) the
+heading's body content (Github readme compatible):
 
 ```text
 # The **beautiful `code`**
+
+## Heading with anchor {#custom-id-123}
 ```
 
 Results in:
 
 ```js
 // [
-//   "h1",
-//   { id: "the-beautiful-code" },
-//   "The ",
-//   [ "strong", {}, "beautiful ", [ "code", {}, "code" ] ]
+//   [
+//     "h1",
+//     { id: "the-beautiful-code" },
+//     "The ",
+//     [ "strong", {}, "beautiful ", [ "code", {}, "code" ] ]
+//   ],
+//   [ "h2", { id: "custom-id-123" }, "Heading with anchor" ]
 // ]
 ```
 
@@ -438,7 +446,7 @@ More info [here](http://thi.ng/hiccup-markdown).
 
 ## Status
 
-**ALPHA** - bleeding edge / work-in-progress
+**STABLE** - used in production
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bhiccup-markdown%5D+in%3Atitle)
 
@@ -462,7 +470,7 @@ For Node.js REPL:
 const hiccupMarkdown = await import("@thi.ng/hiccup-markdown");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.35 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.42 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -110,11 +110,11 @@ export interface TagTransforms {
      *
      * @param ctx
      * @param level
-     * @param id
+     * @param anchorID
      * @param body
      * @param meta
      */
-    heading(ctx: TransformCtx, level: number, id: string, body: any[], meta?: any): any;
+    heading(ctx: TransformCtx, level: number, anchorID: string, body: any[], meta?: any): any;
     /**
      * Horizontal rule handler. Also receives number of dashes used (e.g. to
      * create different representations/styling)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/hiccup-markdown",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Markdown parser & serializer from/to Hiccup format",
   "type": "module",
   "module": "./index.js",
@@ -34,17 +34,17 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.7.2",
-    "@thi.ng/arrays": "^2.5.5",
+    "@thi.ng/api": "^8.7.3",
+    "@thi.ng/arrays": "^2.5.7",
     "@thi.ng/checks": "^3.3.9",
-    "@thi.ng/defmulti": "^2.1.30",
+    "@thi.ng/defmulti": "^2.1.31",
     "@thi.ng/emoji": "^0.1.0",
-    "@thi.ng/errors": "^2.2.11",
-    "@thi.ng/hiccup": "^4.2.33",
+    "@thi.ng/errors": "^2.2.12",
+    "@thi.ng/hiccup": "^4.2.35",
     "@thi.ng/logger": "^1.4.9",
-    "@thi.ng/parse": "^2.2.27",
-    "@thi.ng/strings": "^3.4.0",
-    "@thi.ng/text-canvas": "^2.4.30"
+    "@thi.ng/parse": "^2.2.28",
+    "@thi.ng/strings": "^3.4.1",
+    "@thi.ng/text-canvas": "^2.4.32"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.34.2",
@@ -93,8 +93,7 @@
   },
   "thi.ng": {
     "parent": "@thi.ng/hiccup",
-    "status": "alpha",
     "year": 2018
   },
-  "gitHead": "060a3a69281094df70be0e4f326a0ac3bbc3dd1d\n"
+  "gitHead": "8342900eedc77bb09edb8c544804578b71f8acc6\n"
 }

package/parse.js

@@ -1,4 +1,5 @@
-// thing:no-export
+// Downloaded @ 2023-03-05T09:08:51.082Z
+// Source: https://demo.thi.ng/umbrella/parse-playground/#ldoNwUROTDE6IDxETkw-KyA9PiBkaXNjYXJkIDsKRE5MMjogPE5MPnsyLH0gOwpsYnI6ICdcXCchIDxOTD4hIDsKZXNjOiAnXFwnISAoICc8JyB8ICdbJyB8ICdfJyB8ICcqJyB8ICdgJyB8ICd-JyB8ICc6JyApIDsKaW5saW5lZGVsaW06ICggIiFbIiB8ICdbJyB8ICIqKiIgfCAnXycgfCAnYCcgfCAnPCcgfCAnXFwnIHwgIn5-IiB8ICIgOiIgfCA8bGJyPiApIDsKZGVsaW06ICggPGlubGluZWRlbGltPiB8IDxETkwyPiApIDsKZGVsaW0xOiAoIDxpbmxpbmVkZWxpbT4gfCA8Tkw-ICkgOwpib2R5OiAuKD8tPGRlbGltPiEpID0-IGpvaW4gOwpib2R5MTogLig_LTxkZWxpbTE-ISkgPT4gam9pbiA7Cgp3aWtpcmVmOiAiW1siISAuKD8rIl1dIiEpID0-IGpvaW4gOwpmbnJlZjogIlteIiEgPGxhYmVsPiA7CmZub3RlOiA8TFNUQVJUPiAiW14iISA8Zm5sYWJlbD4gPFdTMT4gPHBhcmE-IDsKZm5sYWJlbDogLig_KyJdOiIhKSA9PiBqb2luIDsKbGFiZWw6IC4oPysnXSchKSA9PiBqb2luIDsKdGFyZ2V0OiAuKD8rJyknISkgPT4gam9pbiA7Cmxpbms6ICdbJyEgPGxpbmtsYWJlbD4gJygnISA8dGFyZ2V0PiA7CmxpbmtyZWY6ICdbJyEgPGxpbmtsYWJlbD4gJ1snISA8bGFiZWw-IDsKbGlua2RlZjogPExTVEFSVD4gJ1snISA8bGFiZWw-ICc6JyEgPFdTMT4gPGxkdGFyZ2V0PiA7CmxkdGFyZ2V0OiAuKD8rPEROTDE-KSA9PiBqb2luIDsKbGlua2xhYmVsOiAoPGltZz4gfCA8Ym9sZD4gfCA8aXRhbGljPiB8IDxzdHJpa2U-IHwgPGNvZGU-IHwgPGVtb2ppPiB8IDxsaW5rYm9keT4pKiAnXSchIDsKbGlua2RlbGltOiAoICIhWyIgfCAnWycgfCAiKioiIHwgJ18nIHwgIn5-IiB8ICdgJyB8ICddJykgOwpsaW5rYm9keTogLig_LTxsaW5rZGVsaW0-ISkgPT4gam9pbiA7CmltZzogIiFbIiEgPGxhYmVsPiAnKCchIDx0YXJnZXQ-IDsKYm9sZDogIioqIiEgKDx3aWtpcmVmPiB8IDxpbWc-IHwgPGZucmVmPiB8IDxsaW5rcmVmPiB8IDxsaW5rPiB8IDxpdGFsaWM-IHwgPHN0cmlrZT4gfCA8Y29kZT4gfCA8ZW1vamk-IHwgPGJvZHkxPikqICIqKiIhIDsKaXRhbGljOiAnXychICg8d2lraXJlZj4gfCA8aW1nPiB8IDxmbnJlZj4gfCA8bGlua3JlZj4gfCA8bGluaz4gfCA8Ym9sZD4gfCA8c3RyaWtlPiB8IDxjb2RlPiB8IDxlbW9qaT4gfCA8Ym9keTE-KSogJ18nISA7CnN0cmlrZTogIn5-IiEgKDx3aWtpcmVmPiB8IDxpbWc-IHwgPGZucmVmPiB8IDxsaW5rcmVmPiB8IDxsaW5rPiB8IDxib2xkPiB8IDxpdGFsaWM-IHwgPGNvZGU-IHwgPGVtb2ppPiB8IDxib2R5MT4pKiAifn4iISA7CmNvZGU6ICdgJyEgLig_KydgJyEpID0-IGpvaW4gOwprYmQ6ICI8a2JkPiIhIC4oPysiPC9rYmQ-IiEpID0-IGpvaW4gOwplbW9qaTogJyAnPyAnOichICg8QUxQSEFfTlVNPiB8ICcrJyB8ICctJykoPysnOichKSA9PiBqb2luIDsKcGFyYTogKDx3aWtpcmVmPiB8IDxpbWc-IHwgPGZucmVmPiB8IDxsaW5rcmVmPiB8IDxsaW5rPiB8IDxib2xkPiB8IDxpdGFsaWM-IHwgPHN0cmlrZT4gfCA8Y29kZT4gfCA8a2JkPiB8IDxlbW9qaT4gfCA8bGJyPiB8IDxlc2M-IHwgPGJvZHk-KSogPEROTDI-ISA7CgpoZGxldmVsOiAnIycrID0-IGNvdW50IDsKaGRpZDogInsjIiEgKDxBTFBIQV9OVU0-IHwgJy0nKSsgJ30nISA9PiBqb2luIDsKaGRkZWxpbTogKCA8ZGVsaW0xPiB8ICJ7IyIgKSA7CmhkYm9keTogLig_LTxoZGRlbGltPiEpID0-IGpvaW4gOwpoZDogPExTVEFSVD4gPGhkbGV2ZWw-IDxXUzA-CiAgICAoPHdpa2lyZWY-IHwgPGltZz4gfCA8Zm5yZWY-IHwgPGxpbms-IHwgPGJvbGQ-IHwgPGl0YWxpYz4gfCA8c3RyaWtlPiB8IDxjb2RlPiB8IDxlbW9qaT4gfCA8aGRib2R5PiApKiA8aGRpZD4_IDxETkwxPiA7CgpsaWxldmVsOiAnICcqID0-IGNvdW50IDsKdWludDogPERJR0lUPisgPT4gaW50IDsKdWxpZDogPEROTD4gPFdTMD4gJy0nISA7Cm9saWQ6IDxETkw-IDxXUzA-IDxESUdJVD4rISAnLichIDsKbGlkZWxpbTogKCA8ZGVsaW0-IHwgPHVsaWQ-IHwgPG9saWQ-ICkgOwpsaWJvZHk6IC4oPy08bGlkZWxpbT4hKSA9PiBqb2luIDsKdG9kbzogJ1snISBbIHhYXSAnXSchIDxXUzE-ID0-IGhvaXN0UiA7CnVsaXRlbTogPExTVEFSVD4gPGxpbGV2ZWw-ICItICIhIDx0b2RvPj8KICAgICAgICAoPHdpa2lyZWY-IHwgPGltZz4gfCA8Zm5yZWY-IHwgPGxpbms-IHwgPGJvbGQ-IHwgPGl0YWxpYz4gfCA8c3RyaWtlPiB8IDxjb2RlPiB8IDxlbW9qaT4gfCA8bGlib2R5PiApKiA8RE5MPiA7Cm9saXRlbTogPExTVEFSVD4gPGxpbGV2ZWw-IDx1aW50PiAiLiAiISA8dG9kbz4_CiAgICAgICAgKDx3aWtpcmVmPiB8IDxpbWc-IHwgPGZucmVmPiB8IDxsaW5rPiB8IDxib2xkPiB8IDxpdGFsaWM-IHwgPHN0cmlrZT4gfCA8Y29kZT4gfCA8ZW1vamk-IHwgPGxpYm9keT4gKSogPEROTD4gOwpsaXN0OiAoPHVsaXRlbT4gfCA8b2xpdGVtPikrIDxETkwxPiA7CgpjYmRlbGltOiA8TFNUQVJUPiAiYGBgIiEgOwpjb2RlYmxvY2s6IDxjYmRlbGltPiEgPGNvZGVtZXRhPiA8Y29kZWJvZHk-IDxETkwxPiA7CmNvZGVtZXRhOiAuKD8rPE5MPiEpID0-IGpvaW4gOwpjb2RlYm9keTogLig_KzxjYmRlbGltPikgPT4gam9pbiA7CgpjdXN0b21kZWxpbTogPExTVEFSVD4gIjo6OiIhIDsKY3VzdG9tYmxvY2s6IDxjdXN0b21kZWxpbT4hIDxjdXN0b21tZXRhPiA8Y3VzdG9tYm9keT4gPEROTDE-IDsKY3VzdG9tbWV0YTogLig_KzxOTD4hKSA9PiBqb2luIDsKY3VzdG9tYm9keTogLig_KzxjdXN0b21kZWxpbT4pID0-IGpvaW4gOwoKbWV0YWJsb2NrOiA8TFNUQVJUPiAie3t7IiEgPG1ldGFib2R5PiA8RE5MMT4gOwptZXRhYm9keTogLig_KzxtZXRhZW5kPiEpID0-IGpvaW4gOwptZXRhZW5kOiAifX19IiA8TEVORD4gOwoKYnFsZXZlbDogJz4nKyA9PiBjb3VudCA7CmJxbGluZTogPExTVEFSVD4gPGJxbGV2ZWw-ICcgJz8hCiAgICAgICAgKDx3aWtpcmVmPiB8IDxpbWc-IHwgPGZucmVmPiB8IDxsaW5rPiB8IDxib2xkPiB8IDxpdGFsaWM-IHwgPHN0cmlrZT4gfCA8Y29kZT4gfCA8ZW1vamk-IHwgPGJxbGJyPiB8IDxib2R5MT4pKiA8RE5MPiA7CmJxbGJyOiAnXFwnISg_LTxETkw-KSA7CmJxdW90ZTogPGJxbGluZT4rIDxETkwxPiA7Cgp0ZGVsaW06ICg8aW5saW5lZGVsaW0-IHwgJ3wnICkgOwp0Ym9keTogLig_LTx0ZGVsaW0-ISkgPT4gam9pbiA7CnRjZWxsOiA8V1MwPiAoPHdpa2lyZWY-IHwgPGltZz4gfCA8Zm5yZWY-IHwgPGxpbms-IHwgPGJvbGQ-IHwgPGl0YWxpYz4gfCA8c3RyaWtlPiB8IDxjb2RlPiB8IDxlbW9qaT4gfCA8dGJvZHk-ICkqICd8JyEgOwp0cm93OiA8TFNUQVJUPiAnfCchIDx0Y2VsbD4oPys8RE5MPikgOwp0YWJsZTogPHRyb3c-KyA8RE5MMT4gOwoKaHI6ICItLSIgJy0nKyA8RE5MMT4gPT4gam9pbiA7CgptYWluOiA8V1MwPiAoPGhkPiB8IDxsaXN0PiB8IDxicXVvdGU-IHwgPGNvZGVibG9jaz4gfCA8Y3VzdG9tYmxvY2s-IHwgPG1ldGFibG9jaz4gfCA8dGFibGU-IHwgPGhyPiB8IDxmbm90ZT4gfCA8bGlua2RlZj4gfCA8cGFyYT4pKiA7pG1haW7aAqgjIEhlbGxvIDp3b3JsZDo6c21pbGU6W15hYmNdIHsjaGQxfQoKIyMgYWJjIHsjaGQyfQojIyBkZWYKCmEgXDwgYgoKTGV0IGBleHAyKHgpID0gMioqeGAKClByZXNzIDxrYmQ-Q29udHJvbDwva2JkPiArIDxrYmQ-Ujwva2JkPiB0byByZWxvYWQuCgo6OjphbGVydApUZXN0IFtsYWJlbF1bcmVmcmVmXQo6OjoKCi0tLQoKe3t7IHsiaWQiOiAxMjMsICJwcm90ZWN0ZWQiOiB0cnVlIH0gfX19ClNvIFtbc21pbGVfZm9vMTJdXSDwn5iNIHdoYXQncyBbdGhpc10oLi90aGlzLm1kKVteMl0gdGhlbjoKCkEgW2xpbmsgX3dpdGggKipuZXN0ZWQgfn5mb3JtYXR-fioqIGFuZCBgcmVmZXJlbmNlYF9dW3JlZnJlZl0uLi4KCmBgYHRzIHRhbmdsZTpubyBsbjp5ZXMKY29uc3QgZm9vID0gNDI7Ci8vIHRoZSBlbmQKYGBgCgoxLiBmb28KICA0LiBiYXIKICAgICBiYXogYW5kIHNvIG9uCiAgICAgbXVsdGlsaW5lCjIuIFsgXSB0YXNrCjMuIFt4XSAqKmRvbmUqKgoKPiBibG9ja3F1b3RlCj4gbXVsdGlsaW5lIHRvb1wKPj4gbmVzdGVkCj4-PiBsZXZlbCAzCj4gLS0gc291cmNlCgp8IGZvbyB8IGJhciB8Cnw6LXwtOnwKfCBbW3JlZiMyMl1dIHwgYG9uYCAqKm9mZioqIHwKClteYWJjXTogRm9vIF9iYXJfIGJhegoKW14yXTogVE9ETwoKW3JlZnJlZl06IGh0dHA6Ly90aGkubmcvCltmb29dOiAuL2Zvby5tZCNiYXIKCtk1MTEuIGFiYwogIC0geHl6CjIxLiB4eHgKICAxLiBmb28KICAgIDEuIGJhcgozMS4geXl5CgrZVj4gKipsZXZlbCAxYSoqCj4-IGxldmVsIDJhCj4-IGxldmVsIDJiCj4KPiBsZXZlbCAxYgoKWyoqZm9vKipdKGJhcikKCioqIVtmb29dKGJhcikqKgoK
 import { peek } from "@thi.ng/arrays/peek";
 import { isArray } from "@thi.ng/checks/is-array";
 import { isPlainObject } from "@thi.ng/checks/is-plain-object";
@@ -44,8 +45,11 @@ emoji: ' '? ':'! (<ALPHA_NUM> | '+' | '-')(?+':'!) => join ;
 para: (<wikiref> | <img> | <fnref> | <linkref> | <link> | <bold> | <italic> | <strike> | <code> | <kbd> | <emoji> | <lbr> | <esc> | <body>)* <DNL2>! ;
 
 hdlevel: '#'+ => count ;
+hdid: "{#"! (<ALPHA_NUM> | '-')+ '}'! => join ;
+hddelim: ( <delim1> | "{#" ) ;
+hdbody: .(?-<hddelim>!) => join ;
 hd: <LSTART> <hdlevel> <WS0>
-    (<wikiref> | <img> | <fnref> | <link> | <bold> | <italic> | <strike> | <code> | <emoji> | <body1> )* <DNL1> ;
+    (<wikiref> | <img> | <fnref> | <link> | <bold> | <italic> | <strike> | <code> | <emoji> | <hdbody> )* <hdid>? <DNL1> ;
 
 lilevel: ' '* => count ;
 uint: <DIGIT>+ => int ;
@@ -258,6 +262,7 @@ export const transformScope = defmulti((x, ctx) => {
     body1: "body",
     bqlbr: "lbr",
     bqline: "repeat0",
+    hdbody: "body",
     label: "body",
     libody: "body",
     linkbody: "body",
@@ -352,9 +357,10 @@ export const transformScope = defmulti((x, ctx) => {
         const body = [];
         const level = children[0].result;
         transformScope(children[1], ctx, body);
-        ctx.headings.push({ level, body });
         __trimBody(body);
-        __collect(acc, ctx.tags.heading(ctx, level, slugifyGH(extractBody(body).join("")), body, ctx.meta));
+        const slug = children[2]?.result || slugifyGH(extractBody(body).join(""));
+        ctx.headings.push({ level, body });
+        __collect(acc, ctx.tags.heading(ctx, level, slug, body, ctx.meta));
         ctx.meta = null;
     },
     hr: (scope, ctx, acc) => {