@knpkv/confluence-to-markdown 0.4.2 → 0.5.0

package/src/ast/BlockNode.ts

@@ -305,28 +305,79 @@ export type BlockQuote = Schema.Schema.Type<typeof BlockQuote>
 /**
  * List item with nested block content.
  *
- * @category BlockNode
- */
-export const ListItem = Schema.Struct({
-  _tag: Schema.Literal("ListItem"),
-  checked: Schema.optional(Schema.Boolean),
-  children: Schema.Array(SimpleBlockNode),
-  rawConfluence: RawConfluence
-})
-
-/**
- * Type for ListItem.
+ * Children may include any simple block as well as nested {@link List} elements.
  *
- * @category Types
+ * @category BlockNode
  */
-export type ListItem = Schema.Schema.Type<typeof ListItem>
+export interface ListItem {
+  readonly _tag: "ListItem"
+  readonly checked?: boolean | undefined
+  readonly children: ReadonlyArray<
+    Heading | Paragraph | CodeBlock | ThematicBreak | Image | Table | UnsupportedBlock | List
+  >
+  readonly rawConfluence?: string | undefined
+}
 
 /**
  * List element (ordered or unordered).
  *
  * @category BlockNode
  */
-export const List = Schema.Struct({
+export interface List {
+  readonly _tag: "List"
+  readonly version: number
+  readonly ordered: boolean
+  readonly start?: number | undefined
+  readonly children: ReadonlyArray<ListItem>
+  readonly rawConfluence?: string | undefined
+}
+
+// Encoded shapes (input to decode): `version` is optional via SchemaVersion's
+// optionalWith({ default }), and the recursive cycle is List → ListItem → List.
+export interface ListEncoded {
+  readonly _tag: "List"
+  readonly version?: number | undefined
+  readonly ordered: boolean
+  readonly start?: number | undefined
+  readonly children: ReadonlyArray<ListItemEncoded>
+  readonly rawConfluence?: string | undefined
+}
+
+export interface ListItemEncoded {
+  readonly _tag: "ListItem"
+  readonly checked?: boolean | undefined
+  readonly children: ReadonlyArray<
+    | Schema.Schema.Encoded<typeof Heading>
+    | Schema.Schema.Encoded<typeof Paragraph>
+    | Schema.Schema.Encoded<typeof CodeBlock>
+    | Schema.Schema.Encoded<typeof ThematicBreak>
+    | Schema.Schema.Encoded<typeof Image>
+    | Schema.Schema.Encoded<typeof Table>
+    | Schema.Schema.Encoded<typeof UnsupportedBlock>
+    | ListEncoded
+  >
+  readonly rawConfluence?: string | undefined
+}
+
+const ListItemChild = Schema.Union(
+  Heading,
+  Paragraph,
+  CodeBlock,
+  ThematicBreak,
+  Image,
+  Table,
+  UnsupportedBlock,
+  Schema.suspend((): Schema.Schema<List, ListEncoded> => List)
+)
+
+export const ListItem: Schema.Schema<ListItem, ListItemEncoded> = Schema.Struct({
+  _tag: Schema.Literal("ListItem"),
+  checked: Schema.optional(Schema.Boolean),
+  children: Schema.Array(ListItemChild),
+  rawConfluence: RawConfluence
+})
+
+export const List: Schema.Schema<List, ListEncoded> = Schema.Struct({
   _tag: Schema.Literal("List"),
   version: SchemaVersion,
   ordered: Schema.Boolean,
@@ -335,13 +386,6 @@ export const List = Schema.Struct({
   rawConfluence: RawConfluence
 })
 
-/**
- * Type for List.
- *
- * @category Types
- */
-export type List = Schema.Schema.Type<typeof List>
-
 /**
  * Task item with status for Confluence task lists.
  *

package/src/parsers/ConfluenceParser.ts

@@ -11,6 +11,7 @@ import {
   CodeBlock,
   Heading,
   Image,
+  type List,
   Paragraph,
   Table,
   TableCell,
@@ -722,12 +723,20 @@ const parseTableRow = (element: HastElement, isHeader: boolean): Effect.Effect<T
 
 /**
  * Parse cell content, unwrapping single <p> elements.
+ *
+ * Confluence's editor frequently emits empty `<p>` placeholders alongside the
+ * real content (e.g. `<p/><p>Must</p>` for a styled cell). Skip those so the
+ * single-real-paragraph case still hits the unwrap path.
  */
 const parseCellContent = (children: Array<HastNode>): Effect.Effect<Array<InlineNode>, ParseError> =>
   Effect.gen(function*() {
-    // Find actual element children (skip whitespace text)
+    const isEmptyParagraph = (el: HastElement): boolean =>
+      el.tagName.toLowerCase() === "p" &&
+      el.children.every((c) => c.type === "text" && !(c as HastText).value.trim())
+
+    // Find actual element children (skip whitespace text and empty <p> placeholders)
     const elementChildren = children.filter((c) => {
-      if (c.type === "element") return true
+      if (c.type === "element") return !isEmptyParagraph(c as HastElement)
       if (c.type === "text" && (c as HastText).value.trim()) return true
       return false
     })
@@ -744,8 +753,8 @@ const parseCellContent = (children: Array<HastNode>): Effect.Effect<Array<Inline
     return yield* hastChildrenToInline(children)
   })
 
-// Type for simple blocks used in lists
-type SimpleBlock = Heading | Paragraph | CodeBlock | ThematicBreak | Image | Table | UnsupportedBlock
+// Type for blocks allowed inside list items: simple blocks plus nested Lists.
+type SimpleBlock = Heading | Paragraph | CodeBlock | ThematicBreak | Image | Table | UnsupportedBlock | List
 
 /**
  * Parse task list element (preprocessed from ac:task-list).
@@ -865,7 +874,7 @@ const parseListItemContent = (
           const el = child as HastElement
           const tagName = el.tagName.toLowerCase()
           if (tagName === "ul" || tagName === "ol") {
-            blocks.push(new UnsupportedBlock({ rawHtml: hastToHtml(el), source: "confluence" }))
+            blocks.push(yield* parseList(el, tagName === "ol"))
           }
         }
       }
@@ -881,12 +890,9 @@ const parseListItemContent = (
       if (tagName === "p") {
         const inlineChildren = yield* hastChildrenToInline(el.children)
         blocks.push(new Paragraph({ children: inlineChildren }))
-      } // Nested lists - convert to paragraph with raw HTML for now (will be handled later)
-      else if (tagName === "ul" || tagName === "ol") {
-        // For nested lists, preserve as unsupported for now
-        blocks.push(new UnsupportedBlock({ rawHtml: hastToHtml(el), source: "confluence" }))
-      } // Other block elements
-      else if (tagName === "pre") {
+      } else if (tagName === "ul" || tagName === "ol") {
+        blocks.push(yield* parseList(el, tagName === "ol"))
+      } else if (tagName === "pre") {
         const codeEl = el.children.find(
           (c): c is HastElement => c.type === "element" && (c as HastElement).tagName === "code"
         )

package/src/parsers/MarkdownParser.ts

@@ -40,7 +40,7 @@ import {
   UnsupportedInline,
   UserMention
 } from "../ast/InlineNode.js"
-import { type InfoPanel, PanelTypes, type TocMacro } from "../ast/MacroNode.js"
+import { type ExpandMacro, type InfoPanel, PanelTypes, type TocMacro } from "../ast/MacroNode.js"
 import { ParseError } from "../SchemaConverterError.js"
 
 // Mdast types (inline to avoid dependency)
@@ -251,17 +251,70 @@ const preprocessContainers = (markdown: string): string => {
 
 /**
  * Convert mdast Root to document nodes.
+ *
+ * Recognises `<details><summary>title</summary>...body...</details>` HTML blocks
+ * and rebuilds them as ExpandMacro nodes so they round-trip back to Confluence.
  */
 const mdastToDocumentNodes = (root: MdastRoot): Effect.Effect<Array<DocumentNode>, ParseError> =>
   Effect.gen(function*() {
     const nodes: Array<DocumentNode> = []
-    for (const child of root.children) {
+    const children = root.children
+    let i = 0
+    while (i < children.length) {
+      const child = children[i]
+      if (!child) {
+        i++
+        continue
+      }
+      if (child.type === "html") {
+        const detailsMatch = (child as MdastHtml).value.match(
+          /^<details(?:\s[^>]*)?>\s*<summary(?:\s[^>]*)?>([\s\S]*?)<\/summary>/
+        )
+        if (detailsMatch) {
+          const title = decodeHtmlEntities(detailsMatch[1] ?? "").trim()
+          let j = i + 1
+          while (j < children.length) {
+            const c = children[j]
+            if (c?.type === "html" && /<\/details>/.test((c as MdastHtml).value)) break
+            j++
+          }
+          const bodyChildren = children.slice(i + 1, j)
+          const bodyBlocks = yield* mdastChildrenToSimpleBlocks(bodyChildren)
+          nodes.push(
+            {
+              _tag: "ExpandMacro" as const,
+              version: 1,
+              ...(title ? { title } : {}),
+              children: bodyBlocks
+            } satisfies ExpandMacro
+          )
+          i = j + 1
+          continue
+        }
+        // Synthetic empty-header marker: drop it and tell the next table to drop
+        // its first row (which the serializer added only to satisfy GFM).
+        if ((child as MdastHtml).value.trim() === "<!--cf:synth-thead-->") {
+          const next = children[i + 1]
+          if (next?.type === "table") {
+            const table = yield* parseTable(next as MdastTable, { dropSyntheticHeader: true })
+            nodes.push(table)
+            i += 2
+            continue
+          }
+          i++
+          continue
+        }
+      }
       const node = yield* mdastNodeToBlock(child)
       if (node !== null) nodes.push(node)
+      i++
     }
     return nodes
   })
 
+const decodeHtmlEntities = (s: string): string =>
+  s.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;/g, "'")
+
 /**
  * Convert mdast node to BlockNode or MacroNode.
  */
@@ -580,6 +633,11 @@ const mdastNodeToInline = (node: MdastNode): Effect.Effect<InlineNode | null, Pa
 
       case "link": {
         const link = node as MdastLink
+        // Recognise the visible round-trip carriers emitted by MarkdownSerializer
+        // for inline macros (`#cf-user:`, `#cf-status:`, `#cf-toc:`) and rebuild
+        // the proper AST node so push back to Confluence is lossless.
+        const macroNode = parseInlineMacroLink(link)
+        if (macroNode) return macroNode
         const children = yield* mdastChildrenToBaseInline(link.children)
         return new Link({
           href: link.url,
@@ -666,6 +724,41 @@ const parseInlineHtml = (html: string): Effect.Effect<InlineNode | null, ParseEr
     return null
   })
 
+/**
+ * Recognise visible markdown links emitted as round-trip carriers for inline
+ * Confluence macros (UserMention, StatusMacro, TocMacro). Returns the rebuilt
+ * AST node, or null if the link is a regular link.
+ *
+ * The raw `<!--cf:status:title;color-->` form expects URL-encoded values;
+ * link text is the human-readable (decoded) form, so we re-encode it here.
+ * URL fragments are already URL-encoded, so they pass through verbatim.
+ */
+const parseInlineMacroLink = (link: MdastLink): InlineNode | null => {
+  const userMatch = link.url.match(/^#cf-user:(.+)$/)
+  if (userMatch) {
+    return new UserMention({ accountId: decodeURIComponent(userMatch[1] ?? "") })
+  }
+  const statusMatch = link.url.match(/^#cf-status:(.*)$/)
+  if (statusMatch) {
+    const text = link.children
+      .filter((c): c is MdastText => c.type === "text")
+      .map((c) => c.value)
+      .join("")
+    return new UnsupportedInline({
+      raw: `<!--cf:status:${encodeURIComponent(text)};${statusMatch[1] ?? ""}-->`,
+      source: "markdown"
+    })
+  }
+  const tocMatch = link.url.match(/^#cf-toc:([^:]*):([^:]*)$/)
+  if (tocMatch) {
+    return new UnsupportedInline({
+      raw: `<!--cf:toc:${tocMatch[1] ?? ""};${tocMatch[2] ?? ""}-->`,
+      source: "markdown"
+    })
+  }
+  return null
+}
+
 /**
  * Parse comment-encoded task list.
  * Format: <!--cf:tasklist:id|uuid|status|body;id|uuid|status|body-->
@@ -1065,16 +1158,16 @@ const mdastChildrenToBaseInline = (
   })
 
 /**
- * Convert mdast children to simple block nodes.
+ * Convert mdast children to block nodes for list items.
+ *
+ * Allows nested {@link NestedList} children — recurses on `list` mdast nodes so
+ * second-level bullets become proper nested markdown lists rather than raw HTML.
  */
-const mdastChildrenToSimpleBlocks = (
+const mdastChildrenToListItemBlocks = (
   children: Array<MdastNode>
-): Effect.Effect<
-  Array<Heading | Paragraph | CodeBlock | ThematicBreak | Image | Table | UnsupportedBlock>,
-  ParseError
-> =>
+): Effect.Effect<Array<SimpleBlock>, ParseError> =>
   Effect.gen(function*() {
-    const blocks: Array<Heading | Paragraph | CodeBlock | ThematicBreak | Image | Table | UnsupportedBlock> = []
+    const blocks: Array<SimpleBlock> = []
     for (const child of children) {
       switch (child.type) {
         case "heading": {
@@ -1116,9 +1209,7 @@ const mdastChildrenToSimpleBlocks = (
           break
         }
         case "list": {
-          // Nested lists - when markdown nested lists are parsed, we lose Confluence local-ids
-          // This should rarely happen as Confluence nested lists are preserved as HTML
-          blocks.push(new UnsupportedBlock({ rawMarkdown: "", source: "markdown" }))
+          blocks.push(yield* parseList(child as MdastList))
           break
         }
         default: {
@@ -1129,8 +1220,44 @@ const mdastChildrenToSimpleBlocks = (
     return blocks
   })
 
-// Type for simple blocks used in lists
-type SimpleBlock = Heading | Paragraph | CodeBlock | ThematicBreak | Image | Table | UnsupportedBlock
+/**
+ * Convert mdast children to simple block nodes (no nested lists).
+ *
+ * Used for AST nodes whose schema does not permit nested lists (BlockQuote etc.).
+ */
+const mdastChildrenToSimpleBlocks = (
+  children: Array<MdastNode>
+): Effect.Effect<
+  Array<Heading | Paragraph | CodeBlock | ThematicBreak | Image | Table | UnsupportedBlock>,
+  ParseError
+> =>
+  Effect.gen(function*() {
+    const blocks = yield* mdastChildrenToListItemBlocks(children)
+    return blocks.map((block) =>
+      block._tag === "List"
+        ? new UnsupportedBlock({ rawMarkdown: "", source: "markdown" })
+        : block
+    )
+  })
+
+// Type for simple blocks used in lists. Recursive: a list item may contain nested Lists.
+type SimpleBlock =
+  | Heading
+  | Paragraph
+  | CodeBlock
+  | ThematicBreak
+  | Image
+  | Table
+  | UnsupportedBlock
+  | NestedList
+
+type NestedList = {
+  _tag: "List"
+  version: number
+  ordered: boolean
+  start?: number
+  children: Array<{ _tag: "ListItem"; checked?: boolean; children: Array<SimpleBlock> }>
+}
 
 /**
  * Parse mdast list.
@@ -1153,7 +1280,7 @@ const parseList = (
     const start = ordered && list.start != null ? list.start : undefined
 
     for (const item of list.children) {
-      const children = yield* mdastChildrenToSimpleBlocks(item.children)
+      const children = yield* mdastChildrenToListItemBlocks(item.children)
       if (item.checked != null) {
         items.push({ _tag: "ListItem", checked: item.checked, children })
       } else {
@@ -1169,8 +1296,17 @@ const parseList = (
 
 /**
  * Parse mdast table.
+ *
+ * `dropSyntheticHeader` is set by `mdastToDocumentNodes` when the table was
+ * preceded by a `<!--cf:synth-thead-->` marker — only then do we discard the
+ * first row (which the serializer added solely to satisfy GFM's required
+ * divider line). A legitimate empty `<thead>` from real Confluence storage is
+ * always preserved.
  */
-const parseTable = (table: MdastTable): Effect.Effect<Table, ParseError> =>
+const parseTable = (
+  table: MdastTable,
+  options: { dropSyntheticHeader?: boolean } = {}
+): Effect.Effect<Table, ParseError> =>
   Effect.gen(function*() {
     let header: TableRow | undefined
     const rows: Array<TableRow> = []
@@ -1194,5 +1330,9 @@ const parseTable = (table: MdastTable): Effect.Effect<Table, ParseError> =>
       }
     }
 
+    if (options.dropSyntheticHeader) {
+      header = undefined
+    }
+
     return new Table({ header, rows })
   })

package/src/schemas/preprocessing/ConfluencePreprocessor.ts

@@ -290,8 +290,17 @@ const processSingleMacro = (macroContent: string): string => {
     return `<span data-macro="status" data-color="${colorMatch?.[1] ?? ""}">${escapeHtml(titleMatch?.[1] ?? "")}</span>`
   }
 
-  // Unknown macro - preserve as unsupported
-  return `<div data-unsupported-macro="${macroName}">${macroContent}</div>`
+  // view-file macro: render as a visible anchor pointing at the attachment.
+  if (macroName === "view-file") {
+    const filenameMatch = macroContent.match(/ri:filename="([^"]+)"/)
+    const filename = filenameMatch?.[1] ?? ""
+    return `<a data-macro="view-file" href="attachment:${escapeHtml(filename)}">${escapeHtml(filename)}</a>`
+  }
+
+  // Unknown macro - preserve as unsupported. The body is HTML-escaped so the
+  // next iteration of processStructuredMacros doesn't re-match the same
+  // <ac:structured-macro> tag and loop forever.
+  return `<div data-unsupported-macro="${macroName}">${escapeHtml(macroContent)}</div>`
 }
 
 /**

package/src/serializers/ConfluenceSerializer.ts

@@ -359,7 +359,7 @@ const serializeTable = (
     return parts.join("")
   })
 
-// Simple block type for list items
+// Simple block type for list items (allows nested Lists for sub-bullets).
 type SimpleBlock =
   | Heading
   | Paragraph
@@ -368,6 +368,15 @@ type SimpleBlock =
   | Image
   | Table
   | UnsupportedBlock
+  | NestedList
+
+// Structural shape of a nested list inside a list item.
+type NestedList = {
+  readonly _tag: "List"
+  readonly ordered: boolean
+  readonly start?: number | undefined
+  readonly children: ReadonlyArray<ListItemType>
+}
 
 // List item type
 type ListItemType = {
@@ -436,6 +445,8 @@ const serializeSimpleBlock = (node: SimpleBlock): Effect.Effect<string, Serializ
         const unsupported = node as unknown as { rawHtml?: string; rawMarkdown?: string }
         return unsupported.rawHtml || unsupported.rawMarkdown || ""
       }
+      case "List":
+        return yield* serializeList(node)
       default:
         return ""
     }
@@ -646,6 +657,15 @@ const serializeInlineNode = (node: InlineNode): Effect.Effect<string, SerializeE
       case "InlineCode":
         return `<code>${escapeHtml(node.value)}</code>`
       case "Link": {
+        // Round-trip view-file macro: a Link with href="attachment:FILENAME"
+        // came from a Confluence ac:structured-macro name="view-file".
+        const attachmentMatch = node.href.match(/^attachment:(.+)$/)
+        if (attachmentMatch) {
+          const filename = attachmentMatch[1] ?? ""
+          return `<ac:structured-macro ac:name="view-file"><ac:parameter ac:name="name"><ri:attachment ri:filename="${
+            escapeHtml(filename)
+          }"/></ac:parameter></ac:structured-macro>`
+        }
         const content = yield* serializeInlineNodes(node.children)
         const title = node.title ? ` title="${escapeHtml(node.title)}"` : ""
         return `<a href="${escapeHtml(node.href)}"${title}>${content}</a>`

package/src/serializers/MarkdownSerializer.ts

@@ -195,7 +195,15 @@ const serializeTable = (
   Effect.gen(function*() {
     const lines: Array<string> = []
 
-    // Header
+    // Markdown tables require a header divider. When the source had no <thead>,
+    // emit a synthetic empty header so the table still renders. A leading
+    // <!--cf:synth-thead--> marker discriminates it from a legitimate empty
+    // header — MarkdownParser strips the marker and drops only that synthetic row,
+    // so a real Confluence <thead> with empty <th>s round-trips intact.
+    const columnCount = node.header?.cells.length ?? node.rows[0]?.cells.length ?? 0
+    const synthMarker = "<!--cf:synth-thead-->"
+    let prefix = ""
+
     if (node.header) {
       const headerCells: Array<string> = []
       for (const cell of node.header.cells) {
@@ -203,6 +211,10 @@ const serializeTable = (
       }
       lines.push(`| ${headerCells.join(" | ")} |`)
       lines.push(`| ${headerCells.map(() => "---").join(" | ")} |`)
+    } else if (columnCount > 0) {
+      prefix = `${synthMarker}\n\n`
+      lines.push(`| ${Array(columnCount).fill("").join(" | ")} |`)
+      lines.push(`| ${Array(columnCount).fill("---").join(" | ")} |`)
     }
 
     // Body rows
@@ -214,10 +226,10 @@ const serializeTable = (
       lines.push(`| ${cells.join(" | ")} |`)
     }
 
-    return lines.join("\n")
+    return `${prefix}${lines.join("\n")}`
   })
 
-// Simple block type for list items
+// Simple block type for list items (allows nested Lists for sub-bullets).
 type SimpleBlock =
   | Heading
   | Paragraph
@@ -226,6 +238,15 @@ type SimpleBlock =
   | Image
   | Table
   | UnsupportedBlock
+  | NestedList
+
+// Structural shape of a nested list inside a list item.
+type NestedList = {
+  readonly _tag: "List"
+  readonly ordered: boolean
+  readonly start?: number | undefined
+  readonly children: ReadonlyArray<ListItemType>
+}
 
 // List item type
 type ListItemType = {
@@ -297,6 +318,8 @@ const serializeSimpleBlock = (node: SimpleBlock): Effect.Effect<string, Serializ
         const unsupported = node as unknown as { rawMarkdown?: string; rawHtml?: string }
         return unsupported.rawMarkdown || unsupported.rawHtml || ""
       }
+      case "List":
+        return yield* serializeList(node)
       default:
         return ""
     }
@@ -339,7 +362,11 @@ const serializeInfoPanel = (
   })
 
 /**
- * Serialize expand macro - use comment encoding for roundtrip.
+ * Serialize expand macro as a GFM-compatible <details> block.
+ *
+ * The opening and closing HTML tags are recognised on round-trip by
+ * MarkdownParser to rebuild the ExpandMacro AST node. Body content is rendered
+ * as ordinary markdown so it shows up in viewers (Obsidian, GitHub, etc.).
  */
 const serializeExpandMacro = (
   node: { title?: string | undefined; children: ReadonlyArray<SimpleBlock> }
@@ -353,11 +380,13 @@ const serializeExpandMacro = (
       contentParts.push(serialized)
     }
 
-    const content = contentParts.join("\n")
-    // Use comment encoding for roundtrip
-    return `<!--cf:expand:${encodeURIComponent(title)}:${encodeURIComponent(content)}-->`
+    const body = contentParts.join("\n\n")
+    const summary = `<summary>${escapeHtml(title)}</summary>`
+    return `<details>\n${summary}\n\n${body}\n\n</details>`
   })
 
+const escapeHtml = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+
 /**
  * Serialize TOC macro.
  */
@@ -470,8 +499,10 @@ const serializeInlineNode = (node: InlineNode): Effect.Effect<string, SerializeE
           encodeURIComponent(node.fallback)
         }-->`
       case "UserMention":
-        // Wrap in HTML comment to prevent remark from parsing
-        return `<!--cf:user:${node.accountId}-->`
+        // Render as a markdown link so the mention is visible in viewers.
+        // The #cf-user: URL fragment is the round-trip carrier — MarkdownParser
+        // rebuilds the UserMention node when it sees a link with that prefix.
+        return `[@${node.accountId}](#cf-user:${encodeURIComponent(node.accountId)})`
       case "DateTime":
         // Wrap in HTML comment to prevent remark from parsing
         return `<!--cf:date:${node.datetime}-->`
@@ -485,8 +516,27 @@ const serializeInlineNode = (node: InlineNode): Effect.Effect<string, SerializeE
         const content = yield* serializeInlineNodes(node.children)
         return `<span style="background-color: ${node.backgroundColor};">${content}</span>`
       }
-      case "UnsupportedInline":
+      case "UnsupportedInline": {
+        // Some inline macros are stored as UnsupportedInline carrying a comment-
+        // encoded round-trip marker. Rewrite the round-trippable ones as visible
+        // markdown links so they show up in viewers; MarkdownParser reverses this.
+        // The raw payload is already URL-encoded (ConfluenceParser uses
+        // encodeURIComponent), so we decode the title for human-readable link
+        // text and pass the encoded value through to the URL fragment as-is.
+        const statusMatch = node.raw.match(/^<!--cf:status:([^;]*);([^;]*)-->$/)
+        if (statusMatch) {
+          const text = decodeURIComponent(statusMatch[1] ?? "")
+          const color = statusMatch[2] ?? ""
+          return `[${text}](#cf-status:${color})`
+        }
+        const tocMatch = node.raw.match(/^<!--cf:toc:([^;]*);([^;]*)-->$/)
+        if (tocMatch) {
+          const min = tocMatch[1] ?? ""
+          const max = tocMatch[2] ?? ""
+          return `[Table of Contents](#cf-toc:${min}:${max})`
+        }
         return node.raw
+      }
       default:
         return ""
     }