mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-19 06:35:44 +01:00
Answer principles round 1: 3 🔴, 8 🟡 (0 misread); attributes as data-*, carried content as paragraphs, links and notes, no character HTML cannot hold, mutants killed
This commit is contained in:
@@ -21,7 +21,7 @@ products store as ADF.
|
||||
drops the rest.
|
||||
- **HTML out:** `adfToHtml` writes paragraphs, headings, lists, quotes, code blocks, images and
|
||||
links as their HTML elements, and every other node as an element holding its JSON and showing its
|
||||
text.
|
||||
content.
|
||||
- **No throws:** every call returns a result; a refusal carries a code from a closed list.
|
||||
- **Runs anywhere:** pure functions with no runtime dependencies, in Node, Deno, Bun and browsers.
|
||||
TypeScript types ship beside the JavaScript.
|
||||
@@ -75,11 +75,30 @@ if (portable.ok) console.log(portable.value)
|
||||
Full reference: [HTML](#html).
|
||||
|
||||
```ts
|
||||
import { adfToHtml } from '@larvit/adf-codec'
|
||||
import { adfToHtml, type AdfDocument } from '@larvit/adf-codec'
|
||||
|
||||
const html = adfToHtml(doc) // the panel above
|
||||
const page: AdfDocument = {
|
||||
content: [
|
||||
{ attrs: { level: 2, localId: 'a1f3' }, content: [{ text: 'Release notes', type: 'text' }], type: 'heading' },
|
||||
{
|
||||
content: [
|
||||
{ text: 'Read the ', type: 'text' },
|
||||
{ marks: [{ attrs: { href: 'https://spec.commonmark.org/' }, type: 'link' }], text: 'spec', type: 'text' },
|
||||
{ text: ', then ask ', type: 'text' },
|
||||
{ attrs: { id: '5b10a2', text: '@Mikael' }, type: 'mention' },
|
||||
],
|
||||
type: 'paragraph',
|
||||
},
|
||||
],
|
||||
type: 'doc',
|
||||
version: 1,
|
||||
}
|
||||
|
||||
// URLs are written as the ADF holds them, javascript: included: sanitize HTML from an author you do not trust before showing it.
|
||||
const html = adfToHtml(page)
|
||||
if (html.ok) console.log(html.value)
|
||||
// <div class="adf-carry" data-adf="{"attrs":{"panelType":"warning"},…}">Check the collation before importing.</div>
|
||||
// <h2 data-local-id="a1f3">Release notes</h2>
|
||||
// <p>Read the <a href="https://spec.commonmark.org/">spec</a>, then ask <span class="adf-carry" data-adf="{"attrs":{"id":"5b10a2","text":"@Mikael"},"type":"mention"}">@Mikael</span></p>
|
||||
```
|
||||
|
||||
### Markdown to ADF
|
||||
@@ -447,9 +466,9 @@ saving what this pair read replaces mentions, attachments and macros with text.
|
||||
## HTML
|
||||
|
||||
Serves [Goals](#goals) 1, 6 and 7. `adfToHtml` writes the HTML element for each node HTML has one
|
||||
for, and keeps every other node whole: an element of class `adf-carry` holds the node's JSON in
|
||||
`data-adf` and shows the node's text, so a reader of the page loses no content. No stylesheet
|
||||
ships. The complete dialect:
|
||||
for, an attribute HTML has none for as `data-*`, and keeps every other node whole: an element of
|
||||
class `adf-carry` holds the node's JSON in `data-adf` and shows the node's content, its links
|
||||
included, so a reader of the page loses no content. No stylesheet ships. The complete dialect:
|
||||
[`spec/html.md`](https://github.com/larvit/adf-codec/blob/main/spec/html.md).
|
||||
|
||||
| ADF | HTML |
|
||||
@@ -464,11 +483,14 @@ ships. The complete dialect:
|
||||
| `paragraph` | `<p>` |
|
||||
| `rule` | `<hr>` |
|
||||
| `text` marked `code`, `em`, `strong` | `<code>`, `<em>`, `<strong>`, the first mark outermost |
|
||||
| any other node, or a node holding what its element cannot | `<div class="adf-carry" data-adf="{…}">its text</div>`, a `<span>` inline |
|
||||
| any other attribute the node's type holds | `data-*` named as HTML's `dataset` names it: `<p data-local-id="a1f3">` |
|
||||
| any other node, or a node holding what its element cannot | `<div class="adf-carry" data-adf="{…}"><p>its content</p></div>`, a `<span>` inline |
|
||||
|
||||
- Text and attribute values are escaped: `&`, `<`, `>`, `"` and a carriage return.
|
||||
- The carry element shows a mention, status or emoji by its text, a date as `2026-09-13` in UTC, a
|
||||
card by its URL, an image by its `alt`, else its URL, and an expand by its title.
|
||||
- Text and attribute values are escaped: `&`, `<`, `>` and `"`. A node holding what HTML cannot
|
||||
hold, such as a carriage return or a control character, rides the carry element.
|
||||
- The carry element shows each block's content as a `<p>`, text a link marks as a link, a mention,
|
||||
status or emoji by its text, a date as `2026-09-13` in UTC, a card as a link to its URL, an image as
|
||||
a link to it, and an expand by its title. What it cannot show leaves a note, `<em>(image)</em>`.
|
||||
- A link's or image's URL is written as the ADF holds it, `javascript:` included: sanitize the
|
||||
HTML before showing a document from an author you do not trust.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user