Repository navigation
fix(options): dedent OPTION-group trailing content to col 0 (#2820) - #2858
Merged
Merged
Conversation
release: v1.40.2 (DEV→main promotion)
Trailing substep content after an [OPTION] group (prose, images, `> [!TIP]` alerts) was leaking as raw markdown inside a code block on rendered tutorials (e.g. hana-clients-install step 3). Root cause: a Hugo shortcode that emits a block-level <div> (os-options/os-panel) closes the surrounding tight numbered list regardless of source indentation (verified against production-pinned Hugo 0.147.7). Once the list closes, Goldmark measures the still-4-space -indented tail from column 0, where the >=4-space rule turns it into a literal indented-code block. Commit 19db8d0 deleted the "Bug B" tail-dedent on the false premise that indented wrappers keep the list open — the Hugo renders disprove that; the list always closes, so the dedent is mandatory. Fix (two parts): - Parser: restore the tail-dedent in convertOptionBlocks — trailing substep content is dedented to column 0 so it renders as sibling markdown; the author's `N.` ordinal reopens the list as <ol start="N"> and numbering continues. - CSS: split the trailing-figure rule so `margin-top/bottom` sets the rhythm without the `margin` shorthand clobbering `margin-left: 1.5rem` — a latent bug the parser fix exposes (the trailing image otherwise jams to the far-left column). Verified before/after on the real production path (composeTutorial -> renderHugoFrontmatter {{% tutorial-step %}} -> Hugo) across hana-clients-install/-hdbsql/-jdbc/-golang: all leaked BEFORE, all CLEAN AFTER. New render-level regression test test/unit/option-tail-leak.test.ts reproduces the leak via the percent-shortcode path (the only path that reproduces it) and asserts the corrected contract. Updated two tests that encoded the old (impossible "nest in <li>") behavior. Design: docs/superpowers/specs/2026-10-20-option-block-rendering-design.md
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
1 participant
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.
Fixes #2820 — raw markdown leaking into a code block when an
[OPTION]group is followed by shared substep content (prose, image,> [!TIP]alerts). Live symptom:hana-clients-installstep 3 showed a "SHELL" box full of literal markdown.Root cause
A Hugo shortcode that emits a block-level
<div>(os-options/os-panel) closes the surrounding tight numbered list regardless of source indentation — verified against production-pinned Hugo 0.147.7. Once the list closes, Goldmark measures the still-4-space-indented trailing content from column 0, where the ≥4-space rule turns it into a literal indented-code block.Commit
19db8d027(the third #2820 fix attempt) regressed this by deleting the "Bug B" tail-dedent, on the false premise that indenting the shortcode wrappers keeps the list open. The Hugo renders disprove that — the list always closes, so the dedent is mandatory. The three prior PRs (#2822, #2826, #2842) each chased the impossible goal of nesting the OPTION block inside the<li>; this PR accepts the honest structure (OPTION block is a sibling of the list) and fixes the actual leak.Fix (two parts)
scripts/parsers/options.ts): restore the tail-dedent — trailing substep content after an OPTION group is dedented to column 0 so it renders as sibling markdown. The author's ownN.ordinal reopens the list as<ol start="N">, so numbering continues.sap-fundamental.src.css): split the trailing-figure rule so vertical rhythm is set withmargin-top/bottominstead of themarginshorthand, which was resettingmargin-left: 1.5remto 0 and jamming the trailing image to the far-left column (a latent bug the parser fix exposes).Verification
Before/after through the real production path (
composeTutorial→renderHugoFrontmatter{{% tutorial-step %}}→ Hugo):test/unit/option-tail-leak.test.tsreproduces the leak via the percent-shortcode path (the only path that reproduces it — rendering at page top level does not) and asserts the corrected contract.options-hugo.test.tsandoption-figure-list-nesting.test.ts, which encoded the old (impossible "nest in<li>") behavior.Design doc:
docs/superpowers/specs/2026-10-20-option-block-rendering-design.md.