mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-20 07:05:44 +01:00
Report how kovetskiy/mark compares with this package
This commit is contained in:
@@ -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).
|
||||||
@@ -826,7 +826,10 @@ Read most (opens and searches):
|
|||||||
Read most (opens and searches):
|
Read most (opens and searches):
|
||||||
|
|
||||||
- `src/markdown/emit/unspellable-runs.ts` 9
|
- `src/markdown/emit/unspellable-runs.ts` 9
|
||||||
|
<<<<<<< HEAD
|
||||||
|
=======
|
||||||
- `src/markdown/emit/unspellable-runs.test.ts` 7
|
- `src/markdown/emit/unspellable-runs.test.ts` 7
|
||||||
|
>>>>>>> origin/main
|
||||||
- `src/markdown/emit/inline-line.ts` 5
|
- `src/markdown/emit/inline-line.ts` 5
|
||||||
- `docs/decisions.md` 4
|
- `docs/decisions.md` 4
|
||||||
- `README.md` 3
|
- `README.md` 3
|
||||||
@@ -835,6 +838,10 @@ Read most (opens and searches):
|
|||||||
- `src/markdown/portable/inline-reduction.ts` 3
|
- `src/markdown/portable/inline-reduction.ts` 3
|
||||||
- `todo.md` 3
|
- `todo.md` 3
|
||||||
- `src/conformance/property-harness.ts` 2
|
- `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
|
## 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
|
- `src/markdown/emit/unspellable-runs.ts` 5
|
||||||
- `todo.md` 5
|
- `todo.md` 5
|
||||||
|
<<<<<<< HEAD
|
||||||
|
=======
|
||||||
- `src/markdown/emit/unspellable-runs.test.ts` 4
|
- `src/markdown/emit/unspellable-runs.test.ts` 4
|
||||||
|
>>>>>>> origin/main
|
||||||
- `README.md` 2
|
- `README.md` 2
|
||||||
- `ci.sh` 2
|
- `ci.sh` 2
|
||||||
- `docs/decisions.md` 2
|
- `docs/decisions.md` 2
|
||||||
@@ -950,3 +960,23 @@ Read most (opens and searches):
|
|||||||
- `AGENTS.md` 1
|
- `AGENTS.md` 1
|
||||||
- `README.md` 1
|
- `README.md` 1
|
||||||
- `publish.sh` 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
|
||||||
|
|||||||
@@ -6,14 +6,14 @@
|
|||||||
|
|
||||||
`Bar = 0.1`
|
`Bar = 0.1`
|
||||||
|
|
||||||
`Next ID = 177`
|
`Next ID = 178`
|
||||||
|
|
||||||
## Items
|
## Items
|
||||||
|
|
||||||
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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
|
`src/markdown/**` bans only `html/`; banning `emit/`, `parse/` and `portable/` for the root's own
|
||||||
files, with its `ci.sh` probe, extends the decision.
|
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
|
The gap: §The comparison table lists every converter that starts and converts covers converters of
|
||||||
README, source and issues, and run its conversion on the corpus's documents where that works with no
|
ADF. The first table lists npm packages that run in Node and convert ADF to or from markdown; the
|
||||||
Confluence account; say which parts were only read. Write the report as one page under `docs/`
|
second lists converters the comparison does not run, and every row of it converts ADF. `mark`
|
||||||
answering:
|
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?
|
Candidate sentence for the entry: "A converter that never reads or writes ADF, such as one writing
|
||||||
- How does it spell the Confluence features we spell as directives, alerts and callouts: macros,
|
Confluence storage format, is left out." Recommended: leave it out, unless the maintainer wants
|
||||||
panels, includes, labels, attachments and page metadata? Where do its spellings and ours differ,
|
non-ADF neighbours listed.
|
||||||
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.
|
|
||||||
|
|
||||||
### 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`.
|
### 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`.
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user