bug(docs write --tab --markdown): Pandoc-style explicit heading anchor `{#slug}` leaks as literal text into the heading

[sebsnyk]

Symptom

gog docs write --replace --markdown --tab=<id> does not consume the Pandoc-style explicit heading-anchor syntax {#slug}. The text {#slug} survives verbatim in the rendered heading instead of being stripped + applied as a stable in-doc anchor (Docs API NamedRange or heading anchor that [text](#slug) links can target).

This is a common pattern for markdown that needs cross-references — authors set explicit anchors so internal [Attachments](#attachments) style links remain stable even if heading text changes. gog's markdown converter handles the reference side since #633 (closed: [text](#slug) resolves to existing heading IDs), but doesn't handle the definition side — author-defined anchors via {#slug} leak as visible characters.

Repro

cat > /tmp/anchor.md <<'MD'
# Top heading

See [Attachments](#attachments) below.

## Attachments {#attachments}

Body of the attachments section.
MD

DOC=$(gog docs create "anchor test" --pageless --file /tmp/anchor.md -j | jq -r .id)
gog docs tabs add "$DOC" --title "Tab 2"
TAB=$(gog docs list-tabs "$DOC" -j | jq -r '.tabs[1].id')

gog docs write "$DOC" --replace --markdown --tab="$TAB" --file /tmp/anchor.md

gog docs read "$DOC" --tab="$TAB"
# Observed: heading reads "Attachments {#attachments}" verbatim
# Expected: heading reads "Attachments"; the anchor "attachments" is registered
#           somewhere the [text](#attachments) link can resolve to.

Expected behaviour

{#slug} at the end of an ATX heading line should be stripped from the rendered heading text and registered as an anchor target the existing [text](#slug) resolver (from #633) can find. Two reasonable implementations:

1. NamedRange on the heading paragraph — gog already emits CreateNamedRange requests in some paths (per feat(docs): named-range create / list / delete / replace-content commands #692 / feat(docs raw): add --tab to traverse a specific tab; default returns tab 0 only #697 context). Wrap the heading paragraph in a NamedRange whose name is the slug; [text](#slug) resolves via NamedRange lookup.
2. Synthetic heading-ID lookup table — keep an in-process map of {slug → heading paragraph startIndex} built during markdown parsing; the link resolver consults the map before falling back to generated IDs.

Either way the visible heading text should NOT contain {#slug}.

Acceptance criteria

• ## Heading text {#anchor-name} in the input markdown produces a Docs heading with rendered text Heading text (no braces, no slug visible).
• A separate [label](#anchor-name) link elsewhere in the same body resolves to that heading on the resulting Doc (clicking the link scrolls to the heading).
• Behaviour matches on both the --tab=<id> path and the whole-doc Drive-import path.
• If the slug already exists from an auto-generated heading ID (gog's existing behaviour), the explicit {#slug} wins and the auto-id is ignored.

References

• Pandoc explicit-header-IDs extension (the de-facto spec for this syntax): https://pandoc.org/MANUAL.html#extension-header_attributes
• Existing link-side resolver: Drive markdown converter: resolve [text](#slug) to heading IDs instead of leaving raw fragment #633 (closed) — Drive markdown converter: resolve [text](#slug) to heading IDs instead of leaving raw fragment.
• Docs API NamedRange (one viable implementation target): https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#NamedRange
• Adjacent same-converter bugs on --tab path: docs write --replace --markdown --tab: paragraph blank lines collapse into soft line breaks #644 (closed), bug(docs write --tab): markdown path drops nested-list nesting (children render as plain text) #696, perf(docs write --tab --markdown): table cells inserted one-per-batchUpdate; multi-table docs trip Docs API write quota #699 + PR perf(docs write --tab --markdown): batch table-cell inserts into single batchUpdate (fixes #699) #701, plus the strikethrough sibling issue filed alongside this one.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 5, 2026, 1:32 PM ET / 17:32 UTC.

Summary
Keep open: current main still treats trailing {#slug} as ordinary heading text in the local Docs markdown path, and the existing heading-link resolver only handles generated slugs after whole-document Drive markdown import.

Reproducibility: yes. from source inspection: parseHeading keeps {#slug} in the heading content and the formatter inserts that text into the Docs request. I did not run the live Google Docs sequence during this read-only review.

Next step
The affected files and validation path are clear, but the fix must coordinate parser metadata, tab rendering, and Drive-import link rewriting.

Review details

Best possible solution:

Add shared explicit-heading-anchor parsing metadata, strip the attribute from rendered heading text, prefer explicit slugs when rewriting same-document links, and cover both tab and whole-document markdown paths with focused unit tests plus live Docs proof.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection: parseHeading keeps {#slug} in the heading content and the formatter inserts that text into the Docs request. I did not run the live Google Docs sequence during this read-only review.

Is this the best way to solve the issue?

Yes, supporting explicit heading anchors inside the existing markdown conversion flow is the narrow maintainable direction. The safer implementation is shared parsing/link-rewrite logic across both paths, not a new flag or separate converter mode.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• I did not run a live Google Docs reproduction in this read-only review; the leak is source-reproducible, but final anchor navigation should be proven against the Docs API after a fix.
• The repair has to keep the local tab renderer and whole-document Drive-import post-processing consistent, including the rule that an explicit slug wins over an auto-generated heading slug.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3d5c9cef65fa.

Label changes

Label changes:

• add P2: This is a normal-priority Docs markdown fidelity issue with a bounded command surface and no emergency data-loss or security signal.
• add impact:other: The issue affects rendered document content and in-doc navigation, which is maintainer-visible but outside the more specific owned impact labels.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.

Label justifications:

• P2: This is a normal-priority Docs markdown fidelity issue with a bounded command surface and no emergency data-loss or security signal.
• impact:other: The issue affects rendered document content and in-doc navigation, which is maintainer-visible but outside the more specific owned impact labels.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd/...
• Live proof when credentials are available: create a temporary doc, add a second tab, write markdown containing ## Attachments {#attachments} and [Attachments](#attachments) through --replace --markdown --tab, then verify the visible heading text omits the attribute and the link navigates to the heading.
• Repeat the live or mocked verification for whole-document docs write --replace --markdown to ensure Drive-import preprocessing/post-processing matches the tab path.

What I checked:

• Repository policy read: The target repository AGENTS.md was read fully before review; its Docs/internal-cmd structure and testing guidance informed the likely repair path. (AGENTS.md:1, 3d5c9cef65fa)
• Heading parser keeps the full heading body: parseHeading captures and returns the entire text after the ATX marker, so ## Attachments {#attachments} is parsed with {#attachments} still in Content. (internal/cmd/docs_markdown.go:692, 3d5c9cef65fa)
• Formatter inserts the parsed heading text: The heading formatter calls ParseInlineFormatting and writes strippedContent directly; there is no explicit-anchor strip or anchor metadata request in the heading branch. (internal/cmd/docs_formatter.go:43, 3d5c9cef65fa)
• Tab markdown path sends that text to Docs: insertDocsMarkdownAt converts markdown with MarkdownToDocsRequests and sends textToInsert in an InsertText request scoped to the tab; no post-pass rewrites local #slug links or creates explicit anchors. (internal/cmd/docs_mutation.go:207, 3d5c9cef65fa)
• Existing resolver is link-side only: rewriteMarkdownHeadingLinks builds slugs from rendered heading text and rewrites links to HeadingId; it does not consume Pandoc header attributes or preserve author-supplied slugs. (internal/cmd/docs_markdown_links.go:28, 3d5c9cef65fa)
• Whole-document path only invokes the existing generated-slug resolver: After Drive markdown import, docs write --replace --markdown calls rewriteMarkdownHeadingLinks only when the source contains ](#; there is no preprocessing for {#slug} before upload. (internal/cmd/docs_edit.go:297, 3d5c9cef65fa)

Likely related people:

• Peter Steinberger: Authored the current release snapshot for the markdown parser/formatter files and the prior generated-heading-link resolver work referenced by this report. (role: recent area contributor; confidence: high; commits: 2c84d8981dd5, b26e19003ebd, e4941e776504; files: internal/cmd/docs_markdown.go, internal/cmd/docs_formatter.go, internal/cmd/docs_markdown_links.go)
• Sebastian Roth: Authored the tab markdown replacement path and native markdown bullet/code rendering work that this issue exercises. (role: introduced adjacent tab markdown behavior; confidence: high; commits: 58b866e9ac55, b646e886f6dd; files: internal/cmd/docs_edit.go, internal/cmd/docs_write_markdown_tab_test.go, internal/cmd/docs_formatter.go)
• chrischall: Recent commits adjusted markdown table/header and multi-table insertion behavior in the same Docs markdown conversion area. (role: adjacent Docs markdown contributor; confidence: medium; commits: 5eb9e14085cf, 97fcd480faa4, 946578dd5af2; files: internal/cmd/docs_markdown.go, internal/cmd/docs_mutation.go, internal/cmd/docs_formatter.go)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.