Report how kovetskiy/mark compares with this package

docs/kovetskiy-mark.md

@@ -0,0 +1,85 @@
+# `kovetskiy/mark` compared with this package
+
+Read and run on 2026-11-09 at `mark` v17.0.0 (`eacff19`): its README, the nine pages under its
+`docs/`, `AGENTS.md`, `go.mod`, the issue search and the storage-format calls in its source. Run: the
+program, built in a `golang:1.27.3` container, with `publish --compile-only` and no network, on 14
+fixtures from `corpus/round-trip/` and on one file of its own syntax. Only read: everything that
+needs a Confluence account (publishing, page lookup, link resolution, attachments, labels, `mark
+export`).
+
+## What it is
+
+A Go program, Apache-2.0, 1,613 stars, 96 open issues, last push 2026-11-05. It publishes markdown
+files as Confluence pages through the REST API, and `mark export` (experimental) writes a page
+back as markdown.
+
+## Which format
+
+Not ADF. It parses markdown with goldmark and writes Confluence **storage format**, an XML dialect
+(`ac:structured-macro`, `ac:task-list`, `<time datetime>`); the source holds no `atlas_doc_format`
+and sends every body as `"representation": "storage"`. Confluence's editor turns that into ADF
+itself, so mark never sees ADF.
+
+It reads a page back only through `mark export`, from storage format, and writes storage format it
+has no markdown for into the markdown as it is, much as the lossless flavour's carry holds a node
+(`docs/export.md` §What stays storage format). Its list of what does not come back the same is
+the same kind as ours.
+
+## How its spellings differ from ours
+
+Each row ran through `mark` and through `commonMarkToAdf`, `losslessMarkdownToAdf` and
+`portableMarkdownToAdf` of v0.3.1.
+
+| Confluence feature | `mark` spells | This package | Difference |
+| --- | --- | --- | --- |
+| Info, tip, note and warning boxes | `> [!NOTE]`, `> Note:`, `!!! note` | `portableMarkdownToAdf` reads `> [!NOTE]` as a `panel`; the lossless flavour spells `!adf:panel warning` | `[!IMPORTANT]`: blue info box in `mark`, `note` panel (purple, as on GitHub) here. `NOTE`, `TIP`, `WARNING` and `CAUTION` give the same box in both (`mark`'s note and warning boxes are ADF's `warning` and `error`). A colon marker and `!!! note` stay a quote and a paragraph here |
+| Expand | `<details><summary>` | `!adf:expand {title="…"}` | `htmlToAdf` and the markdown readers refuse `<details>` as `unmappable-html` until items 137 and 138 |
+| Task list | `- [x]` | `- [x]` in the portable flavour; `!adf:taskList` in the lossless one | the same spelling; `commonMarkToAdf` reads a bullet list, as CommonMark has no task |
+| Date | `@date(2026-07-27)`, `<time datetime>` (behind `--features date`) | `!adf:date{timestamp=…}`; `<time class="adf-date">` in HTML | `<time datetime>` is refused as `unmappable-html`; `@date()` is text here (`docs/decisions.md` §Names stay text) |
+| Emoji | `:tada:` (behind `--features emoji`) | `!adf:emoji[🎉]{…}` | text here, same entry |
+| Link to a page | `[text](ac:Title)`, `./other.md` | a link with that destination | `mark` resolves it with Confluence; here it is a plain link |
+| Status, Jira ticket, table of contents | a macro template: `<!-- Macro: … -->`, `ac:status`, `ac:jira:ticket` | `!adf:status[…]{color=…}`, `!adf:inlineCard{url=…}` | its templates are Go text templates writing storage format; ours are node directives |
+| Mentions, panels with custom colours, media | storage format written by hand, or a template | `!adf:mention`, `!adf:panel custom`, `!adf:mediaSingle` | none in `mark`'s markdown |
+
+What `mark` spells and ADF has no node for, so nothing here corresponds: page metadata in header
+comments or YAML front matter (`Space`, `Parent`, `Title`, `Label`, `Attachment`, `Layout`,
+restrictions, content properties), `<!-- Include: -->` and `<!-- Macro: -->`, attachments,
+footnotes, definition lists, math, and Mermaid, D2 and PlantUML diagrams drawn into images.
+
+Our directives written to `mark` come out as text: every `!adf:` line of the 14 fixtures is
+published as a paragraph holding it. `commonMarkToAdf` refuses a `mark` document that opens with
+`<!-- Space: DOCS -->`, as `unmappable-html`, because a comment is content ADF cannot hold
+(`docs/decisions.md` §Foreign HTML sorts three ways); so does `<!-- Include: -->`. Neither is a
+defect against that entry.
+
+## Which the audience would expect
+
+`mark`'s spellings are the ones the README's people already write: GitHub alerts, `<details>`,
+`- [x]`. Ours agree for alerts and tasks in the portable flavour, and will for `<details>` once
+items 137 and 138 land. The lossless flavour's `!adf:` directives are for what no
+markdown spells, and `mark` spells none of those, so they never compete. The one divergence
+that reads either way is `[!IMPORTANT]`; the README states ours (`README.md` § Portable markdown).
+
+## Overlap
+
+Product managers, engineers and support agents who write markdown for Confluence are the README's
+second audience. `mark` serves them as a publishing pipeline for a repository of documents; this
+package serves the four developer personas who embed a converter. The bot persona (generated
+markdown to ADF) is the one overlap: both turn markdown into Confluence content, but `mark` needs
+an account and the REST API, this package takes none (Goal 8). A user of `mark` who needs ADF can
+publish with `mark` and fetch the page as ADF through the Confluence REST API, which converts
+storage format to ADF; a user of this package who needs storage format has to go to that same API
+(`README.md` § Other ADF converters).
+
+## Does it belong in the comparison table
+
+Neither table fits. The first lists npm packages that run in Node and convert ADF to or from
+markdown; the second lists converters this comparison does not run, and every row of it converts
+ADF. `mark` is a Go program that never touches ADF. Filed as item 177, a question to the maintainer, with the
+options: leave it out, or add a row to the second table saying it converts markdown to storage
+format and not ADF.
+
+## Filed
+
+Only item 177. The differences do not ask for a change to a spelling: `[!IMPORTANT]` is
+an entry's choice to reopen, not a defect, and only a writer panel changes one (`AGENTS.md` §7).

docs/reading-cost.md

@@ -826,7 +826,10 @@ Read most (opens and searches):
 Read most (opens and searches):
 
 - `src/markdown/emit/unspellable-runs.ts` 9
+<<<<<<< HEAD
+=======
 - `src/markdown/emit/unspellable-runs.test.ts` 7
+>>>>>>> origin/main
 - `src/markdown/emit/inline-line.ts` 5
 - `docs/decisions.md` 4
 - `README.md` 3
@@ -835,6 +838,10 @@ Read most (opens and searches):
 - `src/markdown/portable/inline-reduction.ts` 3
 - `todo.md` 3
 - `src/conformance/property-harness.ts` 2
+<<<<<<< HEAD
+- `src/markdown/emit/line-escaping.ts` 2
+=======
+>>>>>>> origin/main
 
 ## Reading cost, chunk 3292be52e286, finished 2026-11-09T04:52:49Z
 
@@ -878,7 +885,10 @@ Read most (opens and searches):
 
 - `src/markdown/emit/unspellable-runs.ts` 5
 - `todo.md` 5
+<<<<<<< HEAD
+=======
 - `src/markdown/emit/unspellable-runs.test.ts` 4
+>>>>>>> origin/main
 - `README.md` 2
 - `ci.sh` 2
 - `docs/decisions.md` 2
@@ -950,3 +960,23 @@ Read most (opens and searches):
 - `AGENTS.md` 1
 - `README.md` 1
 - `publish.sh` 1
+<<<<<<< HEAD
+
+## Reading cost, chunk 0f735d84286c, finished 2026-11-09T08:35:21Z
+
+81347 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `src/markdown/portable/inline-reduction.ts` 4
+- `todo.md` 4
+- `README.md` 3
+- `docs/decisions.md` 3
+- `AGENTS.md` 2
+- `CHANGELOG.md` 2
+- `src/adf/shown-text.ts` 2
+- `src/markdown/portable/adf-to-portable-markdown.test.ts` 2
+- `MIGRATION.md` 1
+- `ci.sh` 1
+=======
+>>>>>>> origin/main

todo.md

@@ -6,14 +6,14 @@
 
 `Bar = 0.1`
 
-`Next ID = 177`
+`Next ID = 178`
 
 ## Items
 
 | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
 |---|---|---|---|---|---|---|---|---|---|---|---|
 | 153 | 0.4.0 |  | question | **Decide whether `src/markdown/` root may import `emit/`, `parse/` or `portable/`, and hold the answer in `.oxlintrc.json` and §The source parts by ADF and format.** | 1 | 2 | 2 | 3 | 2 | code health by 3 | 26.2 |
-| 169 | 0.4.0 |  | owner | **Investigate `kovetskiy/mark` in depth and record in a report how its formats differ from ours, where the two projects overlap and how they compare.** | 1 | 1 | 1 | 1 | 3 | 3 by 4 | 6.3 |
+| 177 | 0.4.0 |  | question | **Decide whether `kovetskiy/mark`, a Go program that writes Confluence storage format and never touches ADF, gets a row in the README's second "Other ADF converters" table, and record the answer in §The comparison table lists every converter that starts and converts.** | 1 | 2 | 1 | 2 | 1 | 3 by 1 | 2.5 |
 | 112 | 0.4.0 |  |  | **Pad a GFM pipe table's short rows with empty cells, read its body rows holding no pipe, and read a one-column table without leading pipes in `portableMarkdownToAdf`.** | 2 | 1 | 2 | 3 | 3 | 4 by 4 | 6.2 |
 | 80 | 0.4.0 |  |  | **Name the node's path and the attribute key when `not-an-adf-document` refuses a node inside the document.** | 2 | 1 | 2 | 3 | 3 | 6 by 4 | 6.0 |
 | 171 | 0.4.0 |  | principle | **Assert the facts an error message must carry, never its whole sentence, in `markdown-to-adf.test.ts`, `document.test.ts` and `html-to-adf.test.ts`.** | 3 | 1 | 1 | 3 | 6 | code health by 3 | 4.4 |
@@ -63,24 +63,18 @@ a paragraph opening with a spellable `!adf:link` (§Nothing recurses unbounded).
 `src/markdown/**` bans only `html/`; banning `emit/`, `parse/` and `portable/` for the root's own
 files, with its `ci.sh` probe, extends the decision.
 
-### 169. Investigate `kovetskiy/mark` in depth and record in a report how its formats differ from ours, where the two projects overlap and how they compare.
+### 177. Decide whether `kovetskiy/mark`, a Go program that writes Confluence storage format and never touches ADF, gets a row in the README's second "Other ADF converters" table, and record the answer in §The comparison table lists every converter that starts and converts.
 
-`https://github.com/kovetskiy/mark` publishes markdown files as Confluence pages. Read its
-README, source and issues, and run its conversion on the corpus's documents where that works with no
-Confluence account; say which parts were only read. Write the report as one page under `docs/`
-answering:
+The gap: §The comparison table lists every converter that starts and converts covers converters of
+ADF. The first table lists npm packages that run in Node and convert ADF to or from markdown; the
+second lists converters the comparison does not run, and every row of it converts ADF. `mark`
+converts markdown to storage format only (`docs/kovetskiy-mark.md` § Does it belong in the
+comparison table). The options: leave it out, or add a row saying it converts markdown to storage
+format and not ADF.
 
-- Which format does it write: ADF, or Confluence's storage format? Can it read a page back?
-- How does it spell the Confluence features we spell as directives, alerts and callouts: macros,
-  panels, includes, labels, attachments and page metadata? Where do its spellings and ours differ,
-  and which would the README's `## Audience` expect?
-- Which personas overlap, and what does a user of one need from the other?
-- Does it belong in the README's "Other ADF converters" table? `docs/decisions.md` §The comparison
-  table lists every converter that starts and converts covers npm packages, and this is a Go
-  program. If it is not ADF at all, that is a question for the maintainer.
-
-The report changes no spelling: one is changed only by a writer panel (`AGENTS.md` §7). A finding
-that asks for a change is filed as its own item.
+Candidate sentence for the entry: "A converter that never reads or writes ADF, such as one writing
+Confluence storage format, is left out." Recommended: leave it out, unless the maintainer wants
+non-ADF neighbours listed.
 
 ### 112. Pad a GFM pipe table's short rows with empty cells, read its body rows holding no pipe, and read a one-column table without leading pipes in `portableMarkdownToAdf`.