feat(docs insert): add --markdown for positional formatted-markdown insertion#854
Conversation
…nsertion `docs insert` placed content at a resolved index (--index/--at/--occurrence) but only as plain text, so a heading or fenced code block landed unformatted. The converted-markdown path already exists internally and is exposed on `docs update --markdown`; this gives `insert` the same capability without deleting anything at the anchor. When --markdown is set, route through the existing insertPreparedDocsMarkdownAt helper at the resolved index and run the heading-link rewrite over the inserted range, mirroring the non-replacing branch of `docs update --markdown`. Reject --markdown with --batch (the markdown path issues its own batchUpdate calls). Closes openclaw#851 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
|
Codex review: needs real behavior proof before merge. Reviewed June 19, 2026, 1:06 PM ET / 17:06 UTC. Summary Reproducibility: yes. for the missing capability: current main has no Review metrics: 2 noteworthy metrics.
Root-cause cluster Members:
Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything. Merge readiness Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch. Rank-up moves:
Proof guidance:
Risk before merge
Maintainer options:
Next step before merge
Security Review detailsBest possible solution: Land the focused flag after maintainer review and redacted real-behavior proof, keeping the linked issue open until the candidate is merged or closed. Do we have a high-confidence way to reproduce the issue? Yes for the missing capability: current main has no Is this the best way to solve the issue? Yes, the proposed approach is the narrow maintainable path: it reuses the existing Docs markdown converter and insertion helper instead of adding a parallel renderer. The remaining merge gate is live behavior proof, not a different implementation shape. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against d2e0bd74809d. Label changesLabel changes:
Label justifications:
Evidence reviewedWhat I checked:
Likely related people:
What the crustacean ranks mean
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics. How this review workflow works
|
clawsweeper
Bot
added
rating: 🧂 unranked krab
|
Landed as ab9a331. Verification:
Caveat: live proof covered anchor placement plus heading/code/list formatting; table, image, and tab variants continue through the pre-existing shared Markdown insertion helper and were covered by existing/unit paths rather than separate live mutations here. |
2 participants
What
Adds
--markdowntogog docs insert, so a formatted markdown block (heading, fenced code block, list, table, image, inline styles) can be inserted at a position resolved by--index/--at/--occurrence, without deleting anything at the anchor.Closes #851.
Why
docs insertalready places content at an arbitrary position, but only as plain text — a heading or fenced code block inserted this way landed as literal, unformatted characters. The converted-markdown path already exists in the codebase and is already exposed ondocs update --markdown(its non-replacing branch). Soinsertwas the only positional command missing a capability the tool already has, which is a discoverability cliff: users reach fordocs insert --markdownfirst, hit an unknown-flag error, and then have to learn that the converted path lives onupdateinstead.How
--markdownbool onDocsInsertCmd.insertPreparedDocsMarkdownAthelper and run the existing heading-link rewrite over the inserted range — mirroring the non-replacing branch ofdocs update --markdown. The shared converter (docsmarkdown.MarkdownToDocsRequests) is already parameterized on an arbitrary base index, so code-fence styling (Roboto Mono + grey shading) and everything else render identically towrite --markdown.--markdownis rejected together with--batch, since the markdown path issues its owndocuments.batchUpdatecalls and cannot be queued into a persisted batch.--markdown) behavior is unchanged.The split between the two commands stays clean:
insert= place at a position, never delete;update --markdown --at/--replace-range= delete-and-replace.Tests
TestDocsInsertCmd_MarkdownAtIndex— asserts a converted heading inserts at the resolved index with the converter's HEADING paragraph-style request (and that an explicit--indexwith no heading links issues no extra GET).TestDocsInsertCmd_MarkdownRejectsBatch— asserts the--markdown+--batchguard.go build ./...,go vet ./internal/cmd/, andgo test ./internal/cmd/all pass. CHANGELOG and the generateddocs insertcommand page + editing guide are updated.