diff --git a/AGENTS.md b/AGENTS.md index 6ecaf7f..5591141 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,7 +25,7 @@ In `docs/decisions.md`: - CommonMark is a subset - Tables - Links -- An image reads as an image only alone in its paragraph, else as its alt text linked; an empty link text reads as its destination +- An image reads as an image only alone in its paragraph, else as its alt text linked; a link text holding nothing a mark rides reads as its destination - Ids stay site-local - Portable task ids come from position - A callout title keeps its link targets diff --git a/README.md b/README.md index dc55948..f2fae1e 100644 --- a/README.md +++ b/README.md @@ -215,7 +215,7 @@ emit refuses: | Code | Fires when | What you can do | | --- | --- | --- | | `unsupported-nesting-depth` | blocks, marks, an attribute's JSON or a carried node's JSON nest past 500 levels | keep the ADF and pass the document over, or show it read-only; flatten the input where you are the one who wrote it | -| `unsupported-node-shape` | parsing, in `losslessMarkdownToAdf`: markdown spells a node with an attribute, value, argument or body its type does not take, or without one it needs, writes as a directive a node or mark the lossless flavour spells as CommonMark, or puts a reserved directive out of place: `!adf:textBreak{}` or `!adf:listBreak` parting nothing, `!adf:doc` anywhere but as the whole document. Emitting: a node carrying one mark type twice, unless it rides the carry as a hard break holding marks or a type `spec/flavour.md` does not spell, a block or a non-text inline node holding `text`, or a leaf block or a non-text inline node holding `content` | fix what the message names; `spec/flavour.md` lists every type's attributes and body | +| `unsupported-node-shape` | parsing, in `losslessMarkdownToAdf`: markdown spells a node with an attribute, value, argument or body its type does not take, or without one it needs, writes as a directive a node or mark the lossless flavour spells as CommonMark, or puts a reserved directive out of place: `!adf:textBreak{}` or `!adf:listBreak` parting nothing, `!adf:doc` anywhere but as the whole document. Emitting: a node carrying one mark type twice, unless it rides the carry, a block or a non-text inline node holding `text`, or a leaf block or a non-text inline node holding `content` | fix what the message names; `spec/flavour.md` lists every type's attributes and body | ## The guarantees diff --git a/docs/decisions.md b/docs/decisions.md index 87a1460..50496f4 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -202,21 +202,20 @@ link reference definition — and a directive link CommonMark could spell is ref link — the bracket form goes literal, the directive form refused — which is CommonMark's prose where its reference implementation nests one `` in another. -## An image reads as an image only alone in its paragraph, else as its alt text linked; an empty link text reads as its destination +## An image reads as an image only alone in its paragraph, else as its alt text linked; a link text holding nothing a mark rides reads as its destination 2026-10-04, the maintainer and a writer panel, 3 of 3; `[]()` 2026-10-09, by Goals 4 and 7, as the maintainer's plan item asked; a link text of hard breaks alone 2026-10-09, by Goal 7. Goals 4, 5, 6 and 7. Valid while `mediaInline` carries no URL and ADF holds no empty text node. -Every reader reads every CommonMark image and empty link, as `spec/flavour.md` §The CommonMark -image and §Marks spell out. An image alone in its paragraph reads as the image, its title as the caption. +Every reader reads every CommonMark image and empty link, as `spec/flavour.md` §The CommonMark image +and §Marks spell out. An image alone in its paragraph reads as the image, its title as the caption. Anywhere else it reads as its alt text linked to its URL, titled by its title. An empty alt text reads as the URL, and an empty link text as its destination; so does a link text holding only hard breaks, which take no marks. `[]()` reads as nothing: it renders nothing, so Goal 7 loses no -content. A link alone in its paragraph whose whole text is one image -reads as that image, with the link marking its `media`. Inside any other link, the alt text is plain -text the link marks, and the image's URL and title drop: the panel chose this by Goal 6, which -outranks Goal 7. +content. A link alone in its paragraph whose whole text is one image reads as that image, with the +link marking its `media`. Inside any other link, the alt text is plain text the link marks, and the +image's URL and title drop: the panel chose this by Goal 6, which outranks Goal 7. In `portableMarkdownToAdf`, a `[!WORD]` marker with no `+` or `-` stands apart from the lines after it, and so does a `+` or `-` callout's title line, so an image alone on the marker line or after the diff --git a/spec/flavour.md b/spec/flavour.md index 73bd968..b9eb949 100644 --- a/spec/flavour.md +++ b/spec/flavour.md @@ -518,12 +518,12 @@ the inline directive `!adf:link[text]{attrs}` only where CommonMark does not: an `href` and `title`, an `href` or `title` no canonical escape spells (a control character, a backslash, an entity reference, an angle bracket beside a space or opening a bare destination, a newline in the title), or a link opening a paragraph whose markdown spelling would read as a link -reference definition. Every such spelling carries an `href`: a directive link CommonMark could -spell is a named error, and so is one spelling none. No link wraps a link at any nesting, which is +reference definition. Every such spelling carries an `href`: a directive link CommonMark could spell +is a named error, and so is one spelling none. No link wraps a link at any nesting, which is CommonMark's own rule: a `[text]` already holding one leaves the outer brackets literal text, and -the directive form, open to no literal reading, is a named error. ADF holds no empty text node, so -a link whose text is empty or holds only hard breaks reads as its destination linked, `[](/url)` as `/url`, and one whose -destination is empty too, `[]()`, as nothing. +the directive form, open to no literal reading, is a named error. ADF holds no empty text node, so a +link whose text is empty or holds only hard breaks reads as its destination linked, `[](/url)` as +`/url`, and one whose destination is empty too, `[]()`, as nothing. - `border` — Attributes: `color` (string, `#rrggbb` or `#rrggbbaa`), `size` (number, 1–3). - `code`, `em`, `strike`, `strong` — Attributes: none.