diff --git a/AGENTS.md b/AGENTS.md index 1bc823b..f9b971d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,6 +94,8 @@ In `docs/decisions.md`: - The real-world corpus holds anonymized documents from sites whose licence it records - The feature table is a section per corpus example, led by a summary table - Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented +- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer drops it instead +- `htmlToAdf` reads any HTML, with no option and no second call ## 1. Nothing about any consumer in the library diff --git a/README.md b/README.md index 71e47db..d40811b 100644 --- a/README.md +++ b/README.md @@ -260,6 +260,14 @@ whatever it costs; the Achieve goals are weighed against each other in the order 8. **Maintain:** Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect. 9. **Maintain:** Fast, and linear in the document's size as JSON. 10. **Maintain:** HTML output holds no style: elements, classes, ids and `data-*` attributes name what a node is. Styling is the consumer's, in a stylesheet of their own. +11. **Achieve:** Converts Jira wiki markup both ways, reading it as Jira renders it. + - Signal: every element in Atlassian's text formatting notation help reads into ADF and writes back. + - Counter-signal: issues report wiki markup that Jira renders differently after a round-trip. + - Why: a converter that skips what Jira renders loses the expands and marks that `WikiMarkupTransformer` loses today. +12. **Achieve:** Reads any HTML into ADF, whatever wrote it. + - Signal: HTML from emails, CMSs and editors reads into ADF without a refusal. + - Counter-signal: `htmlToAdf` gains a special case per source. + - Why: HTML fitted source by source is a reader no developer can predict. ## Audience diff --git a/docs/decisions.md b/docs/decisions.md index a4020be..7a14dc2 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1447,3 +1447,23 @@ alt text. - A card as its address, or its name then ` (address)`, and an extension as its `text`. A card, an extension or a synced block holding no text adds no note in its place. - An expand's title on a line, a blank line above its body. + +## Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer drops it instead + +2026-11-15, the maintainer. Goals 1, 7 and 11. Valid while Jira's renderer reads the `{adf}` macro. +Lands with `todo.md` items 192 to 196. + +The lossless wiki writer spells a node or mark wiki markup has no spelling for as Jira's own +`{adf:display=block}` or `{adf:display=inline}` macro around the node's ADF JSON, so the round-trip +holds and Jira still renders the document. The lossy wiki writer ships beside it for consumers who +want wiki markup alone: it drops the form of what wiki markup cannot spell and keeps its content. + +## `htmlToAdf` reads any HTML, with no option and no second call + +2026-11-15, a developer panel. Goals 6, 8 and 12. Valid while the dialect and foreign HTML read +without ambiguity in one reader. + +HTML from an email, a CMS or an editor reads through `htmlToAdf(html)`, as the dialect does; foreign +elements sort as §Foreign HTML sorts three ways says. The bot, viewer/editor and LLM-pipeline +readers each picked it 3 of 3 over `htmlToAdf(html, { foreign: true })` and `anyHtmlToAdf(html)`: +none of them knows up front whether HTML is foreign, and a flag or a second name makes them guess. diff --git a/docs/reading-cost.md b/docs/reading-cost.md index f990239..07dc545 100644 --- a/docs/reading-cost.md +++ b/docs/reading-cost.md @@ -1229,3 +1229,20 @@ Read most (opens and searches): - `docker-runner.sh` 1 - `src/adf/document.ts` 1 - `src/markdown/emit/inline-runs.ts` 1 + +## Reading cost, chunk 33d8d4c6ebde, finished 2026-11-15T21:43:48Z + +88660 new input tokens before the first commit. + +Read most (opens and searches): + +- `README.md` 9 +- `MIGRATION.md` 8 +- `docs/decisions.md` 5 +- `CHANGELOG.md` 4 +- `ci.sh` 4 +- `src/markdown/parse/markdown-to-adf.test.ts` 4 +- `package.json` 3 +- `spec/unicode/CaseFolding.txt` 3 +- `corpus/README.md` 2 +- `docker-runner.sh` 2