markdown-codec 4.0.7 → 4.0.9
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.
- package/README.md +19 -19
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# markdown-codec
|
|
2
2
|
|
|
3
|
-
[](https://github.com/ExaDev/markdown-codec) [](https://www.npmjs.com/package/markdown-codec) [](https://github.com/ExaDev/documents.js/tree/main/packages/markdown-codec) [](https://www.npmjs.com/package/markdown-codec) [](https://www.npmjs.com/package/markdown-codec) [](https://github.com/ExaDev/documents.js/actions)
|
|
4
4
|
|
|
5
|
-
> Hand-written CommonMark+GFM ⇄ `DocumentPackage` codec, built on [document-schema.js](
|
|
5
|
+
> Hand-written CommonMark+GFM ⇄ `DocumentPackage` codec, built on [document-schema.js](../document-schema.js/README.md).
|
|
6
6
|
|
|
7
|
-
The same "hand-write the format instead of wrapping a third-party library" bet as [`pdf-codec`](
|
|
7
|
+
The same "hand-write the format instead of wrapping a third-party library" bet as [`pdf-codec`](../pdf-codec/README.md), aimed at CommonMark and GFM. No `micromark`/`remark`/`marked`/`markdown-it`/`commonmark`/`mdast`/`unified`/`turndown`/`showdown` dependency (enforced by eslint `no-restricted-imports`). Runtime dependencies: `document-schema.js` (the shared pivot) and `zod`. `readMarkdown`/`writeMarkdown` read and write that pivot's tree-form `DocumentPackage`; `readMarkdownContent`/`writeMarkdownContent` read and write the flat `ContentDocument` underneath it — the same model [`documents.js`](https://github.com/ExaDev/documents.js) builds docx/pptx/odt/odp conversions around. See [Two encodings](#two-encodings-documentpackage-and-contentdocument).
|
|
8
8
|
|
|
9
9
|
```mermaid
|
|
10
10
|
graph TD
|
|
@@ -36,15 +36,15 @@ graph TD
|
|
|
36
36
|
odf --> cli
|
|
37
37
|
pdfcodec --> cli
|
|
38
38
|
|
|
39
|
-
click schema "https://github.com/ExaDev/document-schema.js" "document-schema.js"
|
|
40
|
-
click ooxml "https://github.com/ExaDev/ooxml.js" "ooxml.js"
|
|
41
|
-
click odf "https://github.com/ExaDev/odf.js" "odf.js"
|
|
42
|
-
click pdfcodec "https://github.com/ExaDev/pdf-codec" "pdf-codec"
|
|
43
|
-
click bytecodec "https://github.com/ExaDev/byte-codec" "byte-codec"
|
|
44
|
-
click mdcodec "https://github.com/ExaDev/markdown-codec" "markdown-codec"
|
|
39
|
+
click schema "https://github.com/ExaDev/documents.js/tree/main/packages/document-schema.js" "document-schema.js"
|
|
40
|
+
click ooxml "https://github.com/ExaDev/documents.js/tree/main/packages/ooxml.js" "ooxml.js"
|
|
41
|
+
click odf "https://github.com/ExaDev/documents.js/tree/main/packages/odf.js" "odf.js"
|
|
42
|
+
click pdfcodec "https://github.com/ExaDev/documents.js/tree/main/packages/pdf-codec" "pdf-codec"
|
|
43
|
+
click bytecodec "https://github.com/ExaDev/documents.js/tree/main/packages/byte-codec" "byte-codec"
|
|
44
|
+
click mdcodec "https://github.com/ExaDev/documents.js/tree/main/packages/markdown-codec" "markdown-codec"
|
|
45
45
|
click documents "https://github.com/ExaDev/documents.js" "documents.js"
|
|
46
|
-
click mcp "https://github.com/ExaDev/document-mcp" "document-mcp"
|
|
47
|
-
click cli "https://github.com/ExaDev/document-cli" "document-cli"
|
|
46
|
+
click mcp "https://github.com/ExaDev/documents.js/tree/main/packages/document-mcp" "document-mcp"
|
|
47
|
+
click cli "https://github.com/ExaDev/documents.js/tree/main/packages/document-cli" "document-cli"
|
|
48
48
|
|
|
49
49
|
style mdcodec fill:#f9a825,stroke:#333,stroke-width:3px
|
|
50
50
|
```
|
|
@@ -111,7 +111,7 @@ const bytes2 = z.encode(markdownCodec, documentPackage);
|
|
|
111
111
|
|
|
112
112
|
document-schema.js states one document in two shapes, and owns the transform between them: the flat `ContentDocument` every codec's lowering pipeline actually builds, and the tree-form `DocumentPackage` a serialised artefact carries — sections, headings, lists, and construct boundaries as real nested groups, plus a styles table minted over repeated property tuples. `assemblePackage` goes flat → tree (`decompose` then `factorStyles`), `flattenPackage` goes tree → flat. Only one direction is a genuine round trip: `flattenPackage(assemblePackage(document))` reproduces `document` exactly, for any `ContentDocument` this package's own read side produces (checked against the full CommonMark and GFM conformance corpora, not just a hand-picked fixture — see `src/conformance.test.ts`/`src/gfm-conformance.test.ts`'s own "tree pair matches the flat pair" suite). `assemblePackage(flattenPackage(documentPackage))` does not, in general, reproduce `documentPackage` — a package carrying `definitions`/`layers`/`attachments`/`destinations`/`pages` loses all of them on the way through `flattenPackage`, which carries forward only `metadata` and `symbolTable` (see [Gotchas](#gotchas-and-quirks)).
|
|
113
113
|
|
|
114
|
-
This package exposes a read/write pair and a codec at each level. The unsuffixed names are the tree-form ones and are what to reach for by default — a codec is a construction site, so the tree is what a caller gets unless they ask for otherwise. The `Content`-suffixed names are the flat pair one level down, mirroring the `readXlsx`/`readXlsxContent` naming already in [`ooxml.js`](
|
|
114
|
+
This package exposes a read/write pair and a codec at each level. The unsuffixed names are the tree-form ones and are what to reach for by default — a codec is a construction site, so the tree is what a caller gets unless they ask for otherwise. The `Content`-suffixed names are the flat pair one level down, mirroring the `readXlsx`/`readXlsxContent` naming already in [`ooxml.js`](../ooxml.js/README.md):
|
|
115
115
|
|
|
116
116
|
| Level | Read | Write | Codec | Value type |
|
|
117
117
|
| --- | --- | --- | --- | --- |
|
|
@@ -237,18 +237,16 @@ Every non-passing example is named individually in `src/test-support/conformance
|
|
|
237
237
|
|
|
238
238
|
## Release and publishing
|
|
239
239
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
Release detection diffs `package.json`'s version before/after the release step. Four further jobs gate on that: a `sibling-released` `repository_dispatch` to `documents.js`; a republish under `@exadev/markdown-codec` to GitHub Packages (`GITHUB_TOKEN`); a republish under `mrkdwn.js` to npmjs.org (same OIDC exchange); and an SPDX SBOM + build-provenance attestation signed against the packed tarball.
|
|
240
|
+
Release, CI, and commit-message conventions are all workspace-wide, not package-local — see the [monorepo root README](../../README.md#releases) for the mechanism (topological per-package `semantic-release` via `@exadev/semantic-release-workspace`, OIDC trusted npm publishing, automatic sibling dependency-range rewriting) and its [known gap](../../README.md#releases) note on GitHub Packages republishing and SBOM/provenance signing, both dropped in the migration to this monorepo and not yet restored.
|
|
243
241
|
|
|
244
242
|
## Contributing
|
|
245
243
|
|
|
246
|
-
Conventional Commits enforced by commitlint
|
|
244
|
+
Conventional Commits, enforced workspace-wide by commitlint through a root `commit-msg` hook. Work inside `packages/markdown-codec/`; see the [root README](../../README.md#contributing) for the shared git hooks and history conventions.
|
|
247
245
|
|
|
248
246
|
## References
|
|
249
247
|
|
|
250
|
-
- [document-schema.js](
|
|
251
|
-
- [pdf-codec](
|
|
248
|
+
- [document-schema.js](../document-schema.js/README.md) — owns both shared encodings (`ContentDocument`, `DocumentPackage`) and the `assemblePackage`/`flattenPackage` transform between them.
|
|
249
|
+
- [pdf-codec](../pdf-codec/README.md) — the sibling whose scaffold, tooling, and "hand-write the format" philosophy this project mirrors.
|
|
252
250
|
- [documents.js](https://github.com/ExaDev/documents.js) — bridges markdown to docx/odt/PDF via this package's `ContentDocument` (the flat pair; its own conversion pipeline assembles the package itself). Markdown has no presentation/spreadsheet/drawing variant, so pptx/odp/ods/odg are structurally out of reach.
|
|
253
251
|
- [CommonMark Spec](https://spec.commonmark.org/) — the base specification targeted.
|
|
254
252
|
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) — GFM extensions layered on top.
|
|
@@ -256,10 +254,12 @@ Conventional Commits enforced by commitlint (`commitlint.config.ts`) via a husky
|
|
|
256
254
|
|
|
257
255
|
## npm aliases
|
|
258
256
|
|
|
259
|
-
This package also
|
|
257
|
+
This package also published under an alternate name from the pre-monorepo pipeline:
|
|
260
258
|
|
|
261
259
|
- [mrkdwn.js](https://www.npmjs.com/package/mrkdwn.js)
|
|
262
260
|
|
|
261
|
+
**Frozen since the monorepo migration** — see the [root README's release note](../../README.md#releases): the alias republish step was dropped along with GitHub Packages mirroring and SBOM/provenance signing, and nothing today keeps this name in sync with `markdown-codec`'s own releases. Tracked in [ExaDev/documents.js#728](https://github.com/ExaDev/documents.js/issues/728).
|
|
262
|
+
|
|
263
263
|
## License
|
|
264
264
|
|
|
265
265
|
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "markdown-codec",
|
|
3
|
-
"version": "4.0.
|
|
3
|
+
"version": "4.0.9",
|
|
4
4
|
"description": "Hand-written CommonMark+GFM <-> DocumentPackage codec, built on document-schema.js",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": {
|
|
@@ -8,9 +8,9 @@
|
|
|
8
8
|
"url": "git+https://github.com/ExaDev/documents.js.git",
|
|
9
9
|
"directory": "packages/markdown-codec"
|
|
10
10
|
},
|
|
11
|
-
"homepage": "https://github.com/ExaDev/markdown-codec
|
|
11
|
+
"homepage": "https://github.com/ExaDev/documents.js/tree/main/packages/markdown-codec",
|
|
12
12
|
"bugs": {
|
|
13
|
-
"url": "https://github.com/ExaDev/
|
|
13
|
+
"url": "https://github.com/ExaDev/documents.js/issues"
|
|
14
14
|
},
|
|
15
15
|
"exports": {
|
|
16
16
|
".": {
|
|
@@ -80,7 +80,7 @@
|
|
|
80
80
|
"license": "MIT",
|
|
81
81
|
"packageManager": "pnpm@11.6.0",
|
|
82
82
|
"dependencies": {
|
|
83
|
-
"document-schema.js": "^4.3.
|
|
83
|
+
"document-schema.js": "^4.3.6",
|
|
84
84
|
"zod": "^4.4.3"
|
|
85
85
|
},
|
|
86
86
|
"devDependencies": {
|