fix: preserve the SNIPSTART marker's indentation when splicing - #97
Merged
Conversation
A SNIPSTART marker does not have to sit at column 0. In Markdown it can be nested inside a list item, and in MDX inside a JSX element. spliceFile wrote snippet.fmt() output verbatim, always starting at column 0, which ends the enclosing block: - In a plain Markdown list, the fenced block closes the list item, splitting one <ol> into two. Numbering still renders because the source keeps its literal ordinals, so this went unnoticed. - In MDX, if a JSX element spans the marker, the element is never closed and compilation fails. In the Temporal docs this shows up as "Expected a closing tag for <TabItem> before the end of listItem" on any page with tabs inside a numbered step. Re-apply the marker's own leading whitespace to every non-blank line written between the markers. Blank lines are left alone so no trailing whitespace is introduced, and relative indentation inside the snippet is untouched. Markers already at column 0 get an empty prefix, so existing targets are byte-for-byte unchanged. Verified against the temporalio/documentation tree: the previously failing page now builds, its procedure list renders as a single <ol>, and the Go and Python external storage pages go from two <ol> elements back to one.
Duncanma
approved these changes
Jul 29, 2026
…ndentation # Conflicts: # test/sync.test.js
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was changed
spliceFilewrotesnippet.fmt()output verbatim, always starting at column 0. A SNIPSTART marker does not have to be at column 0 — in Markdown it can be nested inside a list item, and in MDX inside a JSX element. Writing at column 0 under an indented marker ends the enclosing block.This re-applies the marker's own leading whitespace to every non-blank line written between the markers.
Why
Two failure modes, one silent and one fatal.
Silent: in a plain Markdown list, a fenced code block at column 0 closes the list item. One
<ol>becomes two. Numbering still looks right because the source keeps its literal ordinals (2.renders as<ol start=2>), so nobody noticed.Fatal: in MDX, if a JSX element spans the marker, that element is never closed and compilation fails. On
temporalio/documentationthis surfaces as:Any page with
<Tabs>inside a numbered procedure step hits this, which currently blocks wiring those pages to snipsync at all.Details
How this was tested
Three new tests in
test/sync.test.js: indented marker inherits indentation (fence, source link, code, and relative indent all checked, plus no trailing whitespace), column-zero marker is unaffected, and re-running is idempotent.npx jest— 38/38 pass.npx eslint . --ext .js— 0 errors, same 12 pre-existing warnings asmain.Also verified end to end against the
temporalio/documentationtree with real origins:<ol>with tabs and both code blocks intact['<ol>', '<ol start=2>']back to['<ol>']Docs updates needed?
No. Behavior only changes for markers that are not at column 0, which previously could not be used reliably.