orz-markdown 1.4.0 → 1.4.1

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 (5) hide show
  1. package/README.md +31 -0
  2. package/dist/doc-meta.d.ts +3 -3
  3. package/dist/doc-meta.js +3 -3
  4. package/orz-markdown-skills/SKILL.md +15 -0
  5. package/package.json +6 -6
package/README.md CHANGED
@@ -71,6 +71,37 @@ You can also convert a node programmatically:
71
71
  const markdown = window.OrzMarkdownRuntime.elementToMarkdown(someElement);
72
72
  ```
73
73
 
74
+ ## Portable Document Metadata
75
+
76
+ The editable document builders share one metadata model from
77
+ `orz-markdown/doc-meta`. An mdhtml or paged source can declare metadata in a
78
+ leading block that is consumed during generation:
79
+
80
+ ```markdown
81
+ {{nyml
82
+ kind: meta
83
+ title: Field Notes
84
+ author: Your Name
85
+ description: Notes from the field course
86
+ license: CC-BY-4.0
87
+ license_name: Creative Commons Attribution 4.0
88
+ license_url: https://creativecommons.org/licenses/by/4.0/
89
+ source: https://example.org/field-notes
90
+ date: 2026-07-10
91
+ keywords: notes, fieldwork, markdown
92
+ }}
93
+ ```
94
+
95
+ The generated file stores normalized metadata in standard `<head>` tags and an
96
+ `#orz-meta` JSON island. Those records survive in-browser edits and framework
97
+ updates. Host applications can instead pass a `DocMeta` object to the family
98
+ builders; host values win field by field. Slides seed `title` and `author` from
99
+ their native deck config and accept the same programmatic override.
100
+
101
+ ```javascript
102
+ import { extractDocMeta, parseDocMetaIsland } from 'orz-markdown/doc-meta';
103
+ ```
104
+
74
105
  ## Themes
75
106
 
76
107
  We provide multiple ready-to-use CSS themes for rendering the output! You do not need to style the custom plugins from scratch.
package/dist/doc-meta.d.ts CHANGED
@@ -13,9 +13,9 @@
13
13
  *
14
14
  * Two channels, one precedence rule:
15
15
  *
16
- * 1. **In the source** — a `{{nyml kind: meta … }}` block. Travels with the
17
- * markdown, survives every round-trip, and a lone author can type it. nyml
18
- * blocks are non-visible, so nothing leaks into the reader's view.
16
+ * 1. **In the source** — a `{{nyml kind: meta … }}` block that a lone author
17
+ * can type. The builder consumes and removes it, then emits the normalized
18
+ * metadata into the generated document's `<head>`.
19
19
  * 2. **Injected by a host** — the `metadata` build option.
20
20
  *
21
21
  * The **host wins, field by field**: a platform that knows the license
package/dist/doc-meta.js CHANGED
@@ -14,9 +14,9 @@
14
14
  *
15
15
  * Two channels, one precedence rule:
16
16
  *
17
- * 1. **In the source** — a `{{nyml kind: meta … }}` block. Travels with the
18
- * markdown, survives every round-trip, and a lone author can type it. nyml
19
- * blocks are non-visible, so nothing leaks into the reader's view.
17
+ * 1. **In the source** — a `{{nyml kind: meta … }}` block that a lone author
18
+ * can type. The builder consumes and removes it, then emits the normalized
19
+ * metadata into the generated document's `<head>`.
20
20
  * 2. **Injected by a host** — the `metadata` build option.
21
21
  *
22
22
  * The **host wins, field by field**: a platform that knows the license
package/orz-markdown-skills/SKILL.md CHANGED
@@ -74,6 +74,21 @@ The runtime also provides **copy-as-Markdown**: with it loaded, copying a select
74
74
 
75
75
  > **Do not strip `data-md` attributes.** `mermaid`, `smiles`, `qrcode`, `youtube`, and `chart` output carry a `data-md` breadcrumb so copy recovers their source after client-side rendering (e.g. a copied QR yields `{{qr ...}}`, not its SVG). Preserve these attributes if you post-process the HTML.
76
76
 
77
+ ### Portable document metadata
78
+
79
+ The self-contained family shares `DocMeta` from `orz-markdown/doc-meta`:
80
+ `title`, `author`, `description`, `license` (`spdx`, `name`, `url`), `source`,
81
+ `date`, and `keywords`. In mdhtml and paged source, authors may provide a
82
+ `{{nyml kind: meta ...}}` block. The builder consumes that block and emits
83
+ standard `<head>` metadata plus a machine-readable `#orz-meta` JSON island;
84
+ those emitted records survive later in-browser saves and framework updates.
85
+ Host-injected metadata wins field by field. Slides use deck `title:` and
86
+ `author:` as their source metadata and accept the same host override.
87
+
88
+ Use `extractDocMeta`, `mergeDocMeta`, `renderDocMetaHead`,
89
+ `renderDocMetaIsland`, and `parseDocMetaIsland` from
90
+ `orz-markdown/doc-meta`; do not create a second metadata grammar in a host app.
91
+
77
92
  ---
78
93
 
79
94
  ## Themes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "orz-markdown",
3
- "version": "1.4.0",
3
+ "version": "1.4.1",
4
4
  "description": "Customized markdown-it parser with official and custom plugins",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
46
46
  "dependencies": {
47
47
  "@traptitech/markdown-it-katex": "^3.6.0",
48
48
  "katex": "^0.16.35",
49
- "markdown-it": "^14.1.1",
49
+ "markdown-it": "^14.3.0",
50
50
  "markdown-it-anchor": "^9.2.0",
51
51
  "markdown-it-container": "^4.0.0",
52
52
  "markdown-it-footnote": "^4.0.0",
@@ -66,11 +66,11 @@
66
66
  "@types/markdown-it-footnote": "^3.0.4",
67
67
  "@types/node": "^25.3.5",
68
68
  "@types/qrcode-svg": "^1.1.5",
69
- "esbuild": "^0.21.5",
70
- "happy-dom": "^15.11.0",
69
+ "esbuild": "^0.28.1",
70
+ "happy-dom": "^20.10.6",
71
71
  "path-browserify": "^1.0.1",
72
- "tsx": "^4.21.0",
72
+ "tsx": "^4.22.4",
73
73
  "typescript": "^5.9.3",
74
- "vitest": "^4.0.18"
74
+ "vitest": "^4.1.10"
75
75
  }
76
76
  }