mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-21 15:42:58 +01:00
Answer architecture round 2: the decision's title states it whole, an image's title drops inside a link, the readers refuse nesting past 500 levels, one owner for the empty-alt rule
This commit is contained in:
@@ -25,7 +25,7 @@ In `docs/decisions.md`:
|
|||||||
- CommonMark is a subset
|
- CommonMark is a subset
|
||||||
- Tables
|
- Tables
|
||||||
- Links
|
- Links
|
||||||
- What ADF holds no node for reads as a link
|
- Every CommonMark image and empty link reads: the image where it stands alone, else a link
|
||||||
- Ids stay site-local
|
- Ids stay site-local
|
||||||
- Portable task ids come from position
|
- Portable task ids come from position
|
||||||
- A callout title keeps its link targets
|
- A callout title keeps its link targets
|
||||||
|
|||||||
@@ -12,9 +12,9 @@ products store as ADF.
|
|||||||
started from — panels, mentions, statuses and node types this version does not know included.
|
started from — panels, mentions, statuses and node types this version does not know included.
|
||||||
- **Markdown in:** `portableMarkdownToAdf` reads a bot's or a model's markdown, including `~~` and
|
- **Markdown in:** `portableMarkdownToAdf` reads a bot's or a model's markdown, including `~~` and
|
||||||
pipe tables whose every row opens with a pipe. `commonMarkToAdf` reads strict CommonMark as its
|
pipe tables whose every row opens with a pipe. `commonMarkToAdf` reads strict CommonMark as its
|
||||||
spec says: nothing becomes a table, task or panel. Both refuse raw HTML, and
|
spec says: nothing becomes a table, task or panel. Both refuse raw HTML and nesting past 500
|
||||||
`portableMarkdownToAdf` a claimed shape that does not complete
|
levels, and `portableMarkdownToAdf` a claimed shape that does not complete
|
||||||
([The guarantees](#the-guarantees)).
|
([The errors](#the-errors)).
|
||||||
- **Portable markdown, lossy:** `adfToPortableMarkdown` and `portableMarkdownToAdf` convert to and
|
- **Portable markdown, lossy:** `adfToPortableMarkdown` and `portableMarkdownToAdf` convert to and
|
||||||
from the markdown that GitHub, GitLab and Obsidian render — GitHub Flavored Markdown's alerts,
|
from the markdown that GitHub, GitLab and Obsidian render — GitHub Flavored Markdown's alerts,
|
||||||
task lists and pipe tables, Obsidian Flavored Markdown's callouts and highlights.
|
task lists and pipe tables, Obsidian Flavored Markdown's callouts and highlights.
|
||||||
@@ -230,7 +230,8 @@ Serves Goals 1, 4 and 5.
|
|||||||
- Markdown this library reads, and markdown it writes, means what the CommonMark spec says; from
|
- Markdown this library reads, and markdown it writes, means what the CommonMark spec says; from
|
||||||
`0.3.0`, well-formed HTML means what the HTML standard says, read or written. The bullets below
|
`0.3.0`, well-formed HTML means what the HTML standard says, read or written. The bullets below
|
||||||
name every exception.
|
name every exception.
|
||||||
- CommonMark is valid input to `commonMarkToAdf`, apart from the raw HTML `unmappable-html` names.
|
- CommonMark is valid input to `commonMarkToAdf`, apart from the raw HTML `unmappable-html` names
|
||||||
|
and nesting past 500 levels.
|
||||||
- The other readers claim shapes CommonMark reads as text or code. `losslessMarkdownToAdf` claims
|
- The other readers claim shapes CommonMark reads as text or code. `losslessMarkdownToAdf` claims
|
||||||
four: literal text matching directive, pipe-table or strikethrough syntax, and a code fence whose
|
four: literal text matching directive, pipe-table or strikethrough syntax, and a code fence whose
|
||||||
info string opens `adf:`. `portableMarkdownToAdf` claims what [Portable
|
info string opens `adf:`. `portableMarkdownToAdf` claims what [Portable
|
||||||
@@ -245,8 +246,8 @@ Serves Goals 1, 4 and 5.
|
|||||||
- An image anywhere but alone in a plain paragraph reads as its alt text linked to its URL,
|
- An image anywhere but alone in a plain paragraph reads as its alt text linked to its URL,
|
||||||
`See .` as `See [the moon](moon.png).`, and inside a link as plain text
|
`See .` as `See [the moon](moon.png).`, and inside a link as plain text
|
||||||
the link marks.
|
the link marks.
|
||||||
- An image's title reads as its caption where the image stands alone in a plain paragraph, and
|
- An image's title reads as its caption where the image stands alone in a plain paragraph, as
|
||||||
as its link's title where it reads as linked alt text.
|
its link's title where it reads as alt text linked to its URL, and inside a link it drops.
|
||||||
|
|
||||||
And three more: a list continuing past a marker change stays one list against CommonMark's two,
|
And three more: a list continuing past a marker change stays one list against CommonMark's two,
|
||||||
a shortcut reference matching its definition only under Unicode case folding stays unresolved,
|
a shortcut reference matching its definition only under Unicode case folding stays unresolved,
|
||||||
|
|||||||
+5
-4
@@ -202,10 +202,11 @@ 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
|
link — the bracket form goes literal, the directive form refused — which is CommonMark's prose
|
||||||
where its reference implementation nests one `<a>` in another.
|
where its reference implementation nests one `<a>` in another.
|
||||||
|
|
||||||
## What ADF holds no node for reads as a link
|
## Every CommonMark image and empty link reads: the image where it stands alone, else a link
|
||||||
|
|
||||||
2026-10-04, the maintainer and a writer panel, 3 of 3; `[]()` 2026-10-09, by Goals 4 and 7. Goals 4,
|
2026-10-04, the maintainer and a writer panel, 3 of 3; `[]()` 2026-10-09, settled by Goals 4 and 7
|
||||||
5 and 6. Valid while `mediaInline` carries no URL and ADF holds no empty text node.
|
as the maintainer's plan item directed. 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. An image anywhere but alone in a plain
|
Every reader reads every CommonMark image and empty link. An image anywhere but alone in a plain
|
||||||
paragraph reads as its alt text linked to its URL, titled by its title; an empty alt text reads as
|
paragraph reads as its alt text linked to its URL, titled by its title; an empty alt text reads as
|
||||||
@@ -213,7 +214,7 @@ the URL, and an empty link text as its destination. `[]()` reads as nothing: it
|
|||||||
Goal 7 loses no content. A titled image alone in a plain paragraph reads as the image captioned with
|
Goal 7 loses no content. A titled image alone in a plain paragraph reads as the image captioned with
|
||||||
its title. A link alone in a plain paragraph whose whole text is an image reads as the image with
|
its title. A link alone in a plain paragraph whose whole text is an image reads as the image with
|
||||||
the link marking its `media`. Inside a link otherwise, the alt text is plain text the link marks and
|
the link marking its `media`. Inside a link otherwise, the alt text is plain text the link marks and
|
||||||
the image's URL drops: the panel chose this by Goal 6, which outranks Goal 7.
|
the image's URL and title drop: the panel chose this by Goal 6, which outranks Goal 7.
|
||||||
|
|
||||||
## Ids stay site-local
|
## Ids stay site-local
|
||||||
|
|
||||||
|
|||||||
+2
-2
@@ -324,8 +324,8 @@ Anywhere else — beside other content, in a heading, a table cell or an `!adf:p
|
|||||||
reads as its alt text linked to its destination, the link titled by the image's title, since
|
reads as its alt text linked to its destination, the link titled by the image's title, since
|
||||||
`mediaInline` carries a media `collection` + `id`, never a URL. An empty alt text reads as the
|
`mediaInline` carries a media `collection` + `id`, never a URL. An empty alt text reads as the
|
||||||
destination, as an empty link text does. Inside a link's text, the alt text is plain text the link
|
destination, as an empty link text does. Inside a link's text, the alt text is plain text the link
|
||||||
marks, and the image's destination and title drop (`docs/decisions.md` §What ADF holds no node for
|
marks, and the image's destination and title drop (`docs/decisions.md` §Every CommonMark image and
|
||||||
reads as a link).
|
empty link reads).
|
||||||
|
|
||||||
### Tables
|
### Tables
|
||||||
|
|
||||||
|
|||||||
@@ -4,11 +4,10 @@ import { nodeAttrs, nodeContent } from '../../adf/document.ts'
|
|||||||
import { serializeCanonicalJson } from '../../canonical-json.ts'
|
import { serializeCanonicalJson } from '../../canonical-json.ts'
|
||||||
import { tryImageLine } from './inline-line.ts'
|
import { tryImageLine } from './inline-line.ts'
|
||||||
|
|
||||||
// An empty `alt` takes the directive form: `` reads back with no `alt`.
|
|
||||||
export function tryImage(node: AdfNode): string | undefined {
|
export function tryImage(node: AdfNode): string | undefined {
|
||||||
const [media] = nodeContent(node)
|
const [media] = nodeContent(node)
|
||||||
const { alt, url } = media === undefined ? {} : nodeAttrs(media)
|
const { alt, url } = media === undefined ? {} : nodeAttrs(media)
|
||||||
if (typeof url !== 'string' || (alt !== undefined && typeof alt !== 'string') || alt === '') return undefined
|
if (typeof url !== 'string' || (alt !== undefined && typeof alt !== 'string')) return undefined
|
||||||
const read = centeredImage([externalMedia(alt ?? '', url)])
|
const read = centeredImage([externalMedia(alt ?? '', url)])
|
||||||
return serializeCanonicalJson(node, 'compact') === serializeCanonicalJson(read, 'compact') ? tryImageLine(alt, url) : undefined
|
return serializeCanonicalJson(node, 'compact') === serializeCanonicalJson(read, 'compact') ? tryImageLine(alt, url) : undefined
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,10 +1,11 @@
|
|||||||
import type { AdfNode } from '../adf/document.ts'
|
import type { AdfNode } from '../adf/document.ts'
|
||||||
|
|
||||||
// spec/flavour.md, The CommonMark image: the shape `` reads to, and the only one written back as it.
|
// spec/flavour.md, The CommonMark image: `` reads to `centeredImage([externalMedia(alt, url)])`, the only shape written back as it.
|
||||||
export function centeredImage(content: AdfNode[]): AdfNode {
|
export function centeredImage(content: AdfNode[]): AdfNode {
|
||||||
return { attrs: { layout: 'center' }, content, type: 'mediaSingle' }
|
return { attrs: { layout: 'center' }, content, type: 'mediaSingle' }
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// `` builds no `alt`, so a media holding an empty one takes the directive form.
|
||||||
export function externalMedia(alt: string, url: string): AdfNode {
|
export function externalMedia(alt: string, url: string): AdfNode {
|
||||||
return { attrs: alt === '' ? { type: 'external', url } : { alt, type: 'external', url }, type: 'media' }
|
return { attrs: alt === '' ? { type: 'external', url } : { alt, type: 'external', url }, type: 'media' }
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user