From 2b1564db9d10e6f3d8bc9f314acd95c586777a3c Mon Sep 17 00:00:00 2001
From: Will Kahn-Greene <willkg@mozilla.com>
Date: Sun, 30 Aug 2026 08:45:07 -0400
Subject: [PATCH 1/3] docs(README): document <br> for a multi-line table cell

Fixed in #113 but never written up: a table cell that needs more
than one line uses a literal <br>, since a GFM table row has to stay
on one physical line and a real newline isn't an option.
---
 README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/README.md b/README.md
index f46e35c..4ce4961 100644
--- a/README.md
+++ b/README.md
@@ -1000,6 +1000,20 @@ Details:
 - An unknown color name is dropped with a warning and the cell publishes
   uncolored.
 
+**Multi-line table cells** use a literal `<br>` to break a cell onto more than
+one line. A real newline can't be used instead, since a GFM table row has to
+stay on one physical line.
+
+```markdown
+| Field | Notes                      |
+| ----- | -------------------------- |
+| Key   | Type: string<br>JQL: "Key" |
+```
+
+Confluence's own editor represents a multi-line cell as separate paragraphs
+rather than `<br>`; `read`/`export` converts that back to the `<br>` form
+shown above, which is what publishes back to the same paragraphs.
+
 **GitHub alerts** — `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`,
 `[!CAUTION]` — become info/tip/note/warning panels.
 [GFM alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)

From 9090e4336373c3be085ab524e67e41cfa2347b1c Mon Sep 17 00:00:00 2001
From: Will Kahn-Greene <willkg@mozilla.com>
Date: Sun, 30 Aug 2026 08:45:35 -0400
Subject: [PATCH 2/3] fix(convert): pass through a list inside a table cell
 instead of mangling it

Found while writing README documentation for using <ul>/<ol>/<li>
directly in a table cell (a real markdown list needs one line per
item, which a GFM table row can't do). The write side already
handles it -- goldmark's raw HTML passthrough carries the tags into
storage unchanged -- but renderCellLines (added for #113) only
special-cased <p> as a block boundary; a <ul>/<ol> fell into the
inline "run" bucket and rendered as plain inline content with no
separator between items at all. "<ul><li>one</li><li>two</li></ul>"
exported as "onetwo".

renderCellLines now treats <ul>/<ol> as their own line too, passed
through as raw serialized tags rather than converted -- the same
approach already used elsewhere for content that can't be expressed
as pure markdown.

Fixes #115.
---
 CLAUDE.md                              |  2 +-
 README.md                              | 14 +++++++++
 internal/convert/storage_to_md.go      | 26 ++++++++++++-----
 internal/convert/storage_to_md_test.go | 40 ++++++++++++++++++++++++++
 4 files changed, 74 insertions(+), 8 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index f5a3eab..389a770 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -63,7 +63,7 @@ Module `github.com/mozilla/markfluence` (`go 1.25`). `main.go` is a shim to `cmd
 - `internal/pagetree` — `Walk`, the traversal of pages *and folders* under a node, plus `AllDepths`. It is a package rather than command-local because listing a subtree and exporting one (#59) need the identical walk, and its rules must not exist in two copies: siblings arrive from two requests (`/child/page`, `/child/folder`) and are **merged by `extensions.position`**, or the output loses the order Confluence displays; a folder **counts as a level** like a page, which is only reasonable because folders are reported rather than silently traversed; and the walk descends folders even when only pages matter, since a folder may hold the only pages in a subtree. `nodeURL` uses `SiteURL()` — a v1 child row carries `webui` but no `base`. A visited set guards the unbounded case.
 - `internal/pageref` — `Resolve`, the single page-argument resolver: a numeric id, a Confluence page **or folder** URL (`pagePathRE` matches both `/pages/<id>` and `/folder/<id>`, since `children` takes a folder and a folder URL is what a browser hands you — the id is all it returns, so a command that can only use a page reports its own not-found), or a `.md` file whose frontmatter has a `page_id` (stat'd first, so `123.md` is a file). Every command taking a page uses it. `message.go` also owns the wording for the two ways a *frontmatter* `page_id` is wrong — `NotFoundMessage` (caller supplies the remedy, which differs per command) and `NotNumericMessage` — because `create`, `update`, and `fix` all report them and a reader should recognize the same problem across all three. They return strings, not errors: `create` wraps the text in its typed `pageIDFailure` (which also carries the `--json` fields), the others want a plain error. Anything checking a `page_id` before a request uses `IsDigits`, since the API answers a non-numeric id with a 400 whose body says nothing useful.
 - `internal/client` — `ConfluenceClient` over `net/http` with basic auth. Built from a `Config` (site URL, cloud ID, username, token) via `New`; it carries **two bases**: `BaseURL()` is where requests go (the gateway when a cloud ID is set) and `SiteURL()` is always the site. Anything a reader sees uses `SiteURL()` — printed page URLs and, critically, the `baseURL` handed to `convert.MdToConfluence`, since rewritten links are published *into* the page. Pages are Confluence **v2**; attachment writes and the user lookup are **v1** (`/wiki/rest/api/...`). A **folder** — the Cloud content type that can parent a page — has its own v2 route, `GetFolderOrNil` against `/wiki/api/v2/folders/{id}`, because every v2 *page* route answers a folder id with 404; enumerating children, if it is ever added, must be v1, since v2 cannot list inside a folder at all and its page-children route silently omits folders ([docs/confluence/folders.md](docs/confluence/folders.md)). Typed `HTTPError`, per-attempt context timeouts, centralized retry/backoff in `send`. `HTTPError.Error()` appends a **hint** for the three auth failures whose status misleads, matched on the response *body* rather than deduced from the status and always **appended** to it, never replacing it. The one that matters: **a rejected credential is a 404 on every v2 route**, so a revoked token used to make `read` answer `page ... not found` about a page that exists. `RejectedCredential` tells it apart by the fact that every genuine v2 404 *names* what it could not find and the auth one does not, `notFound` gates the three `…OrNil` helpers on it so they stop reading it as "absent", and `jsonout.CodeFor` checks it before the status switch so `--json` reports `AUTH` rather than `NOT_FOUND`. A 403 that is not one of the two measured credential phrasings gets no hint, because that is what a genuine permission denial looks like ([docs/confluence/api.md](docs/confluence/api.md#scopes)). **Retry rules**: 429 for any method; 502/503/504 for idempotent methods; **any other 5xx only when the response carries `Retry-After`** — that is how a 500 becomes retryable, and it is why `parseRetryAfter` reports the header's *presence* apart from its delay (`Retry-After: 0` means "retry now", not "no header"). The exponential delay is jittered, a server-supplied `Retry-After` never is. Decisions go to a package-level hook (`SetRetryLogger`, set once in `root.go` beside `ui.SetDebug`) and fire whichever way they went, because `internal/client` prints nothing and a silent twelve-minute retry storm is otherwise indistinguishable from a hang. **A versioned PUT is not as idempotent as its method**: `SetContentProperty` retry-once on top (recovers a lost create-POST response) and `UpdatePage`'s `updateLanded` both exist for the same reason — a write whose response was lost gets re-sent, and the re-sent version is refused. `updateLanded` requires version *and* title *and* body to match what was sent, since a concurrent edit could have produced the version alone and claiming success over someone else's content is worse than a false failure ([docs/confluence/api.md](docs/confluence/api.md)). `SyncAttachments` (skip/update by a SHA-256 recorded in the attachment's comment, alongside the source path so `read` recovers image paths exactly; only the current comment form is parsed — an attachment stamped by a markfluence predating a comment-format change reads as unmanaged and is re-uploaded once, the same as any hand-uploaded file — except that a *recorded path disagreeing with the local source* is an update even when the checksum matches, so a mangled path repairs itself instead of surviving every later publish; a comment with no source recorded at all is not a disagreement. Every text part of the upload form must go through `writeTextField`, never `multipart.Writer.WriteField`, which emits no charset and gets decoded as Latin-1), `_links.next` pagination. **Three pagination schemes, and picking the wrong one truncates silently.** v1 *child/attachment* collections page through the generic `listV1` helper by `start`/`limit` offset, never `_links.next` (absent when the results fit one page, so it cannot terminate a loop); `ListAttachments`, `ListChildPages`, and `ListChildFolders` all go through it. v2 collections page through `listV2` by the cursor in `_links.next`, which is a `/wiki`-prefixed absolute path `resolveNext` handles unchanged; `ListContentProperties` and `SearchPagesByTitle` share it. **`/wiki/rest/api/search` is neither**: it ignores `start` outright, its `next` is context-relative so it needs the `/wiki` prefix `resolveNext` does not add, a short page does *not* mean the end, and `totalSize` can be nonzero against an empty `results` — so `searchCQL` terminates only on a missing `next` and nothing may branch on `totalSize` ([docs/confluence/search.md](docs/confluence/search.md)). `searchCQLBounded` adds a row bound under it (`SearchCQL` is that call with no bound, which is why `find` is unaffected): it asks for `max+1` and reports the surplus as `more`, since `totalSize` cannot supply a count. Full text goes through `SearchText`/`SearchRawCQL`, which return the cleaned `SearchMatch` the way `FindByTitle` returns `TitleMatch` — and **every field of a match comes from the row's `content` object**, because the row-level `title` is HTML-escaped *and* wrapped in `@@@hl@@@` markers where `content.title` is neither. The `excerpt` exists only at row level, so `cleanExcerpt` strips those markers, unescapes once, and collapses to one line — in the client, so the human and `--json` paths cannot disagree about it. `excerpt=highlight` is passed explicitly and **re-attached when following the cursor** (the `next` link carries `cql` and `limit` but not `excerpt`, and `doJSON` appends params with a bare `?`); an unrecognized value there yields an empty excerpt with a 200, so a rename by Atlassian degrades to no excerpts rather than an error. A row with no `content` object is skipped and **counted** — `type = space` answers with hundreds of them, and a silent skip would report a successful empty result. A bare v1 child row already carries `webui`, `status`, and `extensions.position`, so child listing needs no `expand`. `DownloadAttachment` goes through `send` (inheriting retry/backoff) against `_links.download`; **never** add a `CheckRedirect` that forwards headers — it would leak site credentials to Atlassian's media host, which neither needs nor wants them. `config.go` holds `Resolve` and the `.env` reader. Why each of these is shaped this way, with the evidence: [docs/confluence/api.md](docs/confluence/api.md) and [attachments.md](docs/confluence/attachments.md).
-- `internal/convert` — the converter (the crux). `MdToConfluence(md *frontmatter.MarkdownFile, baseURL, spaceKey, version string) (*ConfluencePage, error)`. It parses with goldmark (GFM) and renders through a custom `storageRenderer` registered at priority 100 (below the default HTML=1000 and table=500 renderers) that emits Confluence storage format. `shield.go` renames raw `ac:`/`ri:` tags to colon-free sentinels around the goldmark step so pasted storage passes through; `callouts.go` is an AST transformer + blockquote renderer for GitHub alerts; `aclink.go` is the *inverse* direction's one element with enough shape to need its own file — `<ac:link>`, which the editor writes for every internal link and `MdToConfluence` never emits, so nothing in the regression suite covers it. One rule decides its whole mapping: **convert when the markdown republishes to a link resolving to the same target, pass the storage through when it would not** — so a page link and a space link convert, while a mention (80% of all real usage), an attachment link (only images are uploaded, so a relative href would be dead) and an unresolvable target stay raw, which the shield republishes byte-identical. A page target is a **title, never an id**, so `PageLinkTargets` reports what needs resolving and `StorageOptions.PageLinks` carries the answers back. An `ac:anchor` is **percent-encoded** where `confluenceSlug` output is not: decode it before matching a heading, leave it encoded inside a URL. A same-page anchor recovers its heading from the document rather than inverting the slug, which is impossible — `confluenceSlug` turns both a space and a hyphen into `-`. The survey the mapping rests on, and the `xml.HTMLAutoClose` trap that made `<ac:link>` crash the parser outright (#88), are in [docs/confluence/links-and-anchors.md](docs/confluence/links-and-anchors.md); `attachname.go` owns the source-path↔attachment-name mapping (percent-encoding `%`→`%25` then `/`→`%2F`, which is **bijective** — that is what makes the dedupe collision-free and lets `read` recover an image's original path; decode refuses an absolute result, which markfluence never produces; what names Confluence accepts is in [docs/confluence/attachments.md](docs/confluence/attachments.md)); `destination.go` owns the **other** codec, destination↔path (`decodeDestination`/`encodeDestination`), shared by images *and* doc links — a markdown destination is a URL, so decode inbound (**before** `withinRoot`, or an encoded `..%2F` slips the clamp) and encode outbound in `storage_to_md.go` (or `export` emits markdown that no longer parses, and `sourceFor`'s absolute-path refusal is undone by the next read); an undecodable destination is a literal `%` in a filename, not an error; the reasoning is in [docs/confluence/links-and-anchors.md](docs/confluence/links-and-anchors.md); `images.go` (resolution stays page-relative like GitHub; the documentation root — cwd — bounds what may be published, and an image above it is `IMAGE BROKEN`), `links.go` (sibling-file scans, GitHub/Confluence slugs, doc-link + anchor rewriting; `docKey` is the single lookup key for both the page and anchor maps. Failure here is **silent** — an unresolved link publishes as a dead relative href with no warning), `tables.go` (the `<table>` tag, stamped with `data-layout="align-start"` so tables auto-size and left-align — this must stay if column widths are ever emitted, or a `<colgroup>` silently induces a layout; plus cells: an AST transformer consumes a leading `<!-- bg:COLOR -->` comment in a cell and `renderTableCell` emits it as `data-highlight-colour`; `storage_to_md.go`'s `cellTexts` reverses this, reading `data-highlight-colour` back into a `bg:` marker (`cellBGNames`, the reverse of `tables.go`'s swatch map — a hex outside the 21 swatches round-trips as the literal hex, and where two names share a hex the British spelling wins, matching Confluence's own `-colour`), and a column's GFM alignment becomes a `<p style="text-align: …">` wrapper **inside** the cell — never the `align` attribute the GFM renderer would emit, which is the one form Confluence discards. Only center and right are emitted: Confluence has no explicit left, so `:---` publishes bare and `read` recovers it as `---`. Since alignment is per-paragraph there and per-column in GFM, `columnSeparators` in `storage_to_md.go` takes each column's most common declared alignment (ties to the first seen) and drops the rest. Rows still fall through to the GFM renderer. A multi-line cell is one `<p>` per line — Enter in the editor starts a new `<p>`, it does not insert a `<br>` — so `renderCellLines` in `storage_to_md.go` joins sibling `<p>` children with a literal `<br>` rather than nothing: a GFM table row is exactly one physical line, so a real newline isn't an option, and the same substitution catches a bare mid-line `<br>` (Shift+Enter) that would otherwise render as the two-space hard break valid in ordinary block content but not inside a table row. Layout values, cell alignment, and colors: [docs/confluence/storage-format.md](docs/confluence/storage-format.md)), and `renderer.go` (code macros, text soft-break→space, images, links) do the rest. The `<!-- confluence-toc -->` and `<!-- markfluence-version -->` token substitutions happen **inside** `MdToConfluence`. `storage_to_md.go`'s `coalesceSplitMarks` repairs a bold/italic span containing a link once Confluence's own editor has touched the page: `MdToConfluence` always nests a mark around a link (`<strong>text <a>link</a></strong>`), but ADF carries marks per text run rather than as nested elements, so any save through the editor re-serializes that into two adjacent runs sharing the mark instead (`<strong>text </strong><a><strong>link</strong></a>`) — rendered independently that produces `**text **[**link**](url)`, whose closing `**` is preceded by a space and so does not open emphasis under CommonMark's flanking rule at all, not merely losing the styling but coming back with literal asterisks. `coalesceSplitMarks` hoists the mark to wrap the whole run, the only shape markdown can express, and only when the link's *entire* content shares the mark — a link only partly marked is left alone, since there's nothing to hoist. The same split happens for an internal `<ac:link>` in place of `<a>` (verified the same way), whose visible text sits one level deeper inside `ac:link-body` rather than directly on the link element — `isLinkNode`/`linkTextBody` cover both shapes.
+- `internal/convert` — the converter (the crux). `MdToConfluence(md *frontmatter.MarkdownFile, baseURL, spaceKey, version string) (*ConfluencePage, error)`. It parses with goldmark (GFM) and renders through a custom `storageRenderer` registered at priority 100 (below the default HTML=1000 and table=500 renderers) that emits Confluence storage format. `shield.go` renames raw `ac:`/`ri:` tags to colon-free sentinels around the goldmark step so pasted storage passes through; `callouts.go` is an AST transformer + blockquote renderer for GitHub alerts; `aclink.go` is the *inverse* direction's one element with enough shape to need its own file — `<ac:link>`, which the editor writes for every internal link and `MdToConfluence` never emits, so nothing in the regression suite covers it. One rule decides its whole mapping: **convert when the markdown republishes to a link resolving to the same target, pass the storage through when it would not** — so a page link and a space link convert, while a mention (80% of all real usage), an attachment link (only images are uploaded, so a relative href would be dead) and an unresolvable target stay raw, which the shield republishes byte-identical. A page target is a **title, never an id**, so `PageLinkTargets` reports what needs resolving and `StorageOptions.PageLinks` carries the answers back. An `ac:anchor` is **percent-encoded** where `confluenceSlug` output is not: decode it before matching a heading, leave it encoded inside a URL. A same-page anchor recovers its heading from the document rather than inverting the slug, which is impossible — `confluenceSlug` turns both a space and a hyphen into `-`. The survey the mapping rests on, and the `xml.HTMLAutoClose` trap that made `<ac:link>` crash the parser outright (#88), are in [docs/confluence/links-and-anchors.md](docs/confluence/links-and-anchors.md); `attachname.go` owns the source-path↔attachment-name mapping (percent-encoding `%`→`%25` then `/`→`%2F`, which is **bijective** — that is what makes the dedupe collision-free and lets `read` recover an image's original path; decode refuses an absolute result, which markfluence never produces; what names Confluence accepts is in [docs/confluence/attachments.md](docs/confluence/attachments.md)); `destination.go` owns the **other** codec, destination↔path (`decodeDestination`/`encodeDestination`), shared by images *and* doc links — a markdown destination is a URL, so decode inbound (**before** `withinRoot`, or an encoded `..%2F` slips the clamp) and encode outbound in `storage_to_md.go` (or `export` emits markdown that no longer parses, and `sourceFor`'s absolute-path refusal is undone by the next read); an undecodable destination is a literal `%` in a filename, not an error; the reasoning is in [docs/confluence/links-and-anchors.md](docs/confluence/links-and-anchors.md); `images.go` (resolution stays page-relative like GitHub; the documentation root — cwd — bounds what may be published, and an image above it is `IMAGE BROKEN`), `links.go` (sibling-file scans, GitHub/Confluence slugs, doc-link + anchor rewriting; `docKey` is the single lookup key for both the page and anchor maps. Failure here is **silent** — an unresolved link publishes as a dead relative href with no warning), `tables.go` (the `<table>` tag, stamped with `data-layout="align-start"` so tables auto-size and left-align — this must stay if column widths are ever emitted, or a `<colgroup>` silently induces a layout; plus cells: an AST transformer consumes a leading `<!-- bg:COLOR -->` comment in a cell and `renderTableCell` emits it as `data-highlight-colour`; `storage_to_md.go`'s `cellTexts` reverses this, reading `data-highlight-colour` back into a `bg:` marker (`cellBGNames`, the reverse of `tables.go`'s swatch map — a hex outside the 21 swatches round-trips as the literal hex, and where two names share a hex the British spelling wins, matching Confluence's own `-colour`), and a column's GFM alignment becomes a `<p style="text-align: …">` wrapper **inside** the cell — never the `align` attribute the GFM renderer would emit, which is the one form Confluence discards. Only center and right are emitted: Confluence has no explicit left, so `:---` publishes bare and `read` recovers it as `---`. Since alignment is per-paragraph there and per-column in GFM, `columnSeparators` in `storage_to_md.go` takes each column's most common declared alignment (ties to the first seen) and drops the rest. Rows still fall through to the GFM renderer. A multi-line cell is one `<p>` per line — Enter in the editor starts a new `<p>`, it does not insert a `<br>` — so `renderCellLines` in `storage_to_md.go` joins sibling `<p>` children with a literal `<br>` rather than nothing: a GFM table row is exactly one physical line, so a real newline isn't an option, and the same substitution catches a bare mid-line `<br>` (Shift+Enter) that would otherwise render as the two-space hard break valid in ordinary block content but not inside a table row. A `<ul>`/`<ol>` found directly in a cell is a third case `renderCellLines` treats as its own line, but passed through as its raw serialized tags rather than converted — a real list needs one line per item, which a single table row can't do at all, so markdown list syntax was never an option there; a cell holding one is only ever raw HTML typed directly into it, matching Confluence's own editor doing the same (`<li><p>…</p></li>`, one `<p>` per item). Layout values, cell alignment, and colors: [docs/confluence/storage-format.md](docs/confluence/storage-format.md)), and `renderer.go` (code macros, text soft-break→space, images, links) do the rest. The `<!-- confluence-toc -->` and `<!-- markfluence-version -->` token substitutions happen **inside** `MdToConfluence`. `storage_to_md.go`'s `coalesceSplitMarks` repairs a bold/italic span containing a link once Confluence's own editor has touched the page: `MdToConfluence` always nests a mark around a link (`<strong>text <a>link</a></strong>`), but ADF carries marks per text run rather than as nested elements, so any save through the editor re-serializes that into two adjacent runs sharing the mark instead (`<strong>text </strong><a><strong>link</strong></a>`) — rendered independently that produces `**text **[**link**](url)`, whose closing `**` is preceded by a space and so does not open emphasis under CommonMark's flanking rule at all, not merely losing the styling but coming back with literal asterisks. `coalesceSplitMarks` hoists the mark to wrap the whole run, the only shape markdown can express, and only when the link's *entire* content shares the mark — a link only partly marked is left alone, since there's nothing to hoist. The same split happens for an internal `<ac:link>` in place of `<a>` (verified the same way), whose visible text sits one level deeper inside `ac:link-body` rather than directly on the link element — `isLinkNode`/`linkTextBody` cover both shapes.
 - `internal/frontmatter` — flat YAML frontmatter parse/quote/`UpdateField`, and the `MarkdownFile` type (`Parse`/`ParseFile`, exported `Filename`/`Content`/`Frontmatter`/`Body`, and `Title`/`PageID`/`Space`/`Parent` accessors that normalize missing/blank/`"null"`).
 - `internal/pagewidth` — the `page_width` `Width` enum (`narrow`/`wide`/`max`, default `max`), `Declared`, the vocab↔content-property maps, `WidthFromProperties`, and `Apply`/`Read` against the client. Width lives in two content properties and **both** must be written or the reader and the editor disagree: [docs/confluence/page-width.md](docs/confluence/page-width.md).
 - `internal/schematest` — the `--json` drift guard, and the reason the schema can't fall behind the code. `ValidateEnvelope`/`ValidateError` validate an emitted document against the embedded schema; `document.go` checks the schema *document* instead (`Commands`, plus tests that every name in the `command` enum has an `if/then` branch that constrains `results.items` **and** `summary`). That last one matters because outside a branch the schema says only "results is an array": a command added to the enum without a branch is completely unvalidated, and adding just the enum entry is exactly how a new command's conformance test goes green. `cmd`'s `TestCommandEnumMatchesRegisteredCommands` closes the loop from the other side — every registered subcommand is in the enum or in that test's `noJSONEnvelope` list. Two rules keep all this working: **every result field lives on a typed struct and nothing uses `omitempty`** (so every field always marshals and `additionalProperties:false`/`required` catch an added, renamed, or removed one no matter what a fixture sets — never build a result as a `map[string]any`), and **a conformance test builds its document with the command's own builder** (`failEnvelope`, `jsonResult`) rather than a hand-copied literal, or it validates a copy while the real output drifts.
diff --git a/README.md b/README.md
index 4ce4961..486adfc 100644
--- a/README.md
+++ b/README.md
@@ -1014,6 +1014,20 @@ Confluence's own editor represents a multi-line cell as separate paragraphs
 rather than `<br>`; `read`/`export` converts that back to the `<br>` form
 shown above, which is what publishes back to the same paragraphs.
 
+**Lists in table cells** use HTML list tags — `<ul>`, `<ol>`, and `<li>` —
+directly in the cell, the same way `<br>` is used for a plain line break.
+Markdown's own list syntax needs each item on its own line, which a table row
+can't do, so it isn't an option here.
+
+```markdown
+| Field  | Values                                |
+| ------ | ------------------------------------- |
+| Status | <ul><li>open</li><li>closed</li></ul> |
+```
+
+`read`/`export` recovers the same tags rather than converting them to
+anything else.
+
 **GitHub alerts** — `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`,
 `[!CAUTION]` — become info/tip/note/warning panels.
 [GFM alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
diff --git a/internal/convert/storage_to_md.go b/internal/convert/storage_to_md.go
index ed87ff1..d1849f3 100644
--- a/internal/convert/storage_to_md.go
+++ b/internal/convert/storage_to_md.go
@@ -475,15 +475,27 @@ func (r *mdRenderer) renderCellLines(c *snode) string {
 		run = nil
 	}
 	for _, k := range c.kids {
-		if k.name != "p" {
+		switch k.name {
+		case "p":
+			flush()
+			// An empty <p> is a deliberate blank line (Enter twice in the
+			// editor), not the absence of one -- unlike an empty run, which is
+			// just the lack of any non-<p> content between two <p>s and
+			// contributes no line at all.
+			lines = append(lines, r.renderInlineChildren(k))
+		case "ul", "ol":
+			// A GFM table row is one physical line, so a real bulleted or
+			// numbered list -- which needs one line per item -- can't be
+			// expressed as markdown list syntax inside a cell at all.
+			// Passthrough as the raw tags, which markfluence's own write side
+			// already accepts typed directly into a cell (goldmark's raw HTML
+			// passes through unchanged), keeps it exact instead of running
+			// every item together the way rendering it as inline content would.
+			flush()
+			lines = append(lines, serialize(k))
+		default:
 			run = append(run, k)
-			continue
 		}
-		flush()
-		// An empty <p> is a deliberate blank line (Enter twice in the editor),
-		// not the absence of one -- unlike an empty run, which is just the lack
-		// of any non-<p> content between two <p>s and contributes no line at all.
-		lines = append(lines, r.renderInlineChildren(k))
 	}
 	flush()
 	return strings.ReplaceAll(strings.Join(lines, "<br>"), "  \n", "<br>")
diff --git a/internal/convert/storage_to_md_test.go b/internal/convert/storage_to_md_test.go
index aef66bf..50a0e66 100644
--- a/internal/convert/storage_to_md_test.go
+++ b/internal/convert/storage_to_md_test.go
@@ -240,6 +240,46 @@ func TestStorageToMarkdownJoinsMultilineCells(t *testing.T) {
 	}
 }
 
+// TestStorageToMarkdownPassesThroughListsInCells checks that a <ul>/<ol>
+// found directly in a table cell round-trips as raw HTML rather than being
+// rendered as inline content -- a GFM table row is exactly one physical line,
+// so a real list (one line per item) can't be expressed as markdown list
+// syntax inside a cell at all, and rendering it the way ordinary inline
+// content is ran every item together with no separator: "<ul><li>one</li>
+// <li>two</li></ul>" became "onetwo".
+func TestStorageToMarkdownPassesThroughListsInCells(t *testing.T) {
+	// The <li><p>...</p></li> form is what Confluence's own editor writes for
+	// a list authored inside a cell in the browser; markfluence's own write
+	// side (a <ul> typed directly into a markdown cell) never adds the <p>,
+	// since goldmark's raw HTML passthrough carries it through unchanged.
+	in := `<table><tbody><tr>` +
+		`<td><ul><li>one</li><li>two</li></ul></td>` +
+		`<td><ol><li><p>a</p></li><li><p>b</p></li></ol></td>` +
+		`</tr></tbody></table>`
+	want := "| <ul><li>one</li><li>two</li></ul> | <ol><li><p>a</p></li><li><p>b</p></li></ol> |\n" +
+		"| --- | --- |\n"
+
+	got, err := convert.StorageToMarkdown(in, convert.StorageOptions{})
+	if err != nil {
+		t.Fatalf("StorageToMarkdown: %v", err)
+	}
+	if got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+
+	// The passthrough form must itself be stable end to end: publishing the
+	// exported markdown must reproduce the exact storage read in above.
+	md := frontmatter.Parse("main.md", got)
+	root := testRoot(t, "")
+	page, err := convert.MdToConfluence(md, root, testIndex(t, root), "https://wiki.example.net", "ENG", "vtest")
+	if err != nil {
+		t.Fatalf("MdToConfluence: %v", err)
+	}
+	if !strings.Contains(page.HTML, `<ul><li>one</li><li>two</li></ul>`) {
+		t.Errorf("published storage lost the list:\n%s", page.HTML)
+	}
+}
+
 // TestStorageToMarkdownStripsGeneratedIDs checks that the server-generated
 // ac:macro-id and ac:local-id attributes are dropped from passthrough output.
 func TestStorageToMarkdownStripsGeneratedIDs(t *testing.T) {

From b24be9dc5d2c8700deca18f7f505aa1721322006 Mon Sep 17 00:00:00 2001
From: Will Kahn-Greene <willkg@mozilla.com>
Date: Sun, 30 Aug 2026 08:54:11 -0400
Subject: [PATCH 3/3] fix(convert): don't pipe-escape a passed-through list's
 raw HTML

Code review found that cellTexts's blanket "|" -> "\|" escape --
needed so literal pipe text doesn't get read as a column boundary in
the single-line row a cell becomes -- was also being applied to the
<ul>/<ol> passthrough this fix added. A backslash has no escaping
meaning inside a quoted HTML attribute, so a link's href containing
a "|" inside a passed-through list came back corrupted with a
literal backslash baked in, which republishing would make permanent.

Moved the escape into renderCellLines itself, applied only to
rendered <p>/inline text, never to serialize's raw output. The same
root cause reaches a plain <a href> outside any list too, which
predates this fix and is filed separately as #116 -- fixing that
needs the escape to apply to a link's text and not its destination,
which isn't reachable from cellTexts once the two are already
merged into one rendered string.
---
 internal/convert/storage_to_md.go      | 13 ++++++++++---
 internal/convert/storage_to_md_test.go | 13 +++++++++++--
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/internal/convert/storage_to_md.go b/internal/convert/storage_to_md.go
index d1849f3..c2a7b06 100644
--- a/internal/convert/storage_to_md.go
+++ b/internal/convert/storage_to_md.go
@@ -434,7 +434,7 @@ func (r *mdRenderer) cellTexts(tr *snode) []string {
 	var cells []string
 	for _, c := range tr.kids {
 		if c.name == "th" || c.name == "td" {
-			text := strings.ReplaceAll(r.renderCellLines(c), "|", `\|`)
+			text := r.renderCellLines(c)
 			if marker := cellBGMarkerComment(c); marker != "" {
 				if text == "" {
 					text = marker
@@ -465,12 +465,19 @@ func (r *mdRenderer) cellTexts(tr *snode) []string {
 func (r *mdRenderer) renderCellLines(c *snode) string {
 	var lines []string
 	var run []*snode
+	// escapeCellPipe protects a literal "|" in rendered text from being read as
+	// a column boundary in the single-line table row this becomes. It must
+	// never be applied to serialize's raw-HTML passthrough below: a "|" there
+	// can be inside a quoted attribute (a link's href, say), where a backslash
+	// has no escaping meaning at all and would corrupt the value verbatim
+	// on the next publish instead of protecting anything.
+	escapeCellPipe := func(s string) string { return strings.ReplaceAll(s, "|", `\|`) }
 	flush := func() {
 		if len(run) == 0 {
 			return
 		}
 		if s := r.renderInlineChildren(&snode{kids: run}); s != "" {
-			lines = append(lines, s)
+			lines = append(lines, escapeCellPipe(s))
 		}
 		run = nil
 	}
@@ -482,7 +489,7 @@ func (r *mdRenderer) renderCellLines(c *snode) string {
 			// editor), not the absence of one -- unlike an empty run, which is
 			// just the lack of any non-<p> content between two <p>s and
 			// contributes no line at all.
-			lines = append(lines, r.renderInlineChildren(k))
+			lines = append(lines, escapeCellPipe(r.renderInlineChildren(k)))
 		case "ul", "ol":
 			// A GFM table row is one physical line, so a real bulleted or
 			// numbered list -- which needs one line per item -- can't be
diff --git a/internal/convert/storage_to_md_test.go b/internal/convert/storage_to_md_test.go
index 50a0e66..313e1ff 100644
--- a/internal/convert/storage_to_md_test.go
+++ b/internal/convert/storage_to_md_test.go
@@ -252,12 +252,21 @@ func TestStorageToMarkdownPassesThroughListsInCells(t *testing.T) {
 	// a list authored inside a cell in the browser; markfluence's own write
 	// side (a <ul> typed directly into a markdown cell) never adds the <p>,
 	// since goldmark's raw HTML passthrough carries it through unchanged.
+	// The third cell's link href carries a literal "|": code review on the
+	// original fix found that reusing cellTexts's blanket "|" -> "\|" escape
+	// (needed so literal pipe *text* doesn't get read as a column boundary in
+	// the single-line row a cell becomes) against serialize's raw-HTML output
+	// would corrupt the href with a backslash that has no meaning inside a
+	// quoted attribute -- a URL, unlike table text, has no escaping syntax at
+	// all, so this must come back byte-identical.
 	in := `<table><tbody><tr>` +
 		`<td><ul><li>one</li><li>two</li></ul></td>` +
 		`<td><ol><li><p>a</p></li><li><p>b</p></li></ol></td>` +
+		`<td><ul><li><a href="https://example.com/a|b">c</a></li></ul></td>` +
 		`</tr></tbody></table>`
-	want := "| <ul><li>one</li><li>two</li></ul> | <ol><li><p>a</p></li><li><p>b</p></li></ol> |\n" +
-		"| --- | --- |\n"
+	want := "| <ul><li>one</li><li>two</li></ul> | <ol><li><p>a</p></li><li><p>b</p></li></ol> |" +
+		` <ul><li><a href="https://example.com/a|b">c</a></li></ul> |` + "\n" +
+		"| --- | --- | --- |\n"
 
 	got, err := convert.StorageToMarkdown(in, convert.StorageOptions{})
 	if err != nil {