Repository navigation
🐛 Show button line blocks as separate lines - #308
Merged
chrisjsewell merged 12 commits intoNov 9, 2026
Merged
Conversation
button-link parsed its body as inline text, so an RST line-block bar stayed on the page. Bars indented under an option were parsed as a block quote and still kept the bar. AI-assisted (Cursor). The account owner confirmed this can be submitted.
AI-assisted (Cursor). The account owner confirmed this can be submitted.
Follow docutils' line-block syntax: the first non-blank line must start
with "|" and then a space (or end there). Text that starts with a
substitution ("|sub| text") is then parsed once, as before, instead of
twice: the second parse duplicated side effects, such as an autonumbered
footnote reference ("Too many autonumbered footnote references").
Continuation lines are now accepted too. MyST text is never
block-parsed: line blocks are RST syntax, and the extra parse reported
MyST's warnings twice.
Move the parsed inline nodes into the button rather than copying them:
docutils registers footnote references on the document, so a copied one
was never numbered and crashed the HTML writer (KeyError: 'refid').
The tests cover button-link and button-ref, the markup from executablebooks#156, a
blank line between bars, continuation lines, nested lines and inline
markup.
A raw HTML <br> is dropped by the LaTeX, text, man and texinfo writers,
which then joined the lines ("heynew line"). Use an sd_line_break node
instead: <br /> in HTML, \newline{} in LaTeX (it compiles inside
\sphinxhref with pdflatex and xelatex), and a space in the other
builders and in astext().
The whole button was one gettext message, and its text ran the lines together. Each line is now a message of its own, as in a normal line block (msgids "hey" and "new line"), and each translated line keeps its place.
An RST line block, or a MyST hard line break (a backslash at the end of the line). The live example also puts the LaTeX line break through the PDF build.
Check every line at the outermost indent, not only the first one, so that a line block followed by a paragraph is parsed once, as inline text, instead of being block-parsed and then parsed again (which repeated messages, raised a spurious "Too many autonumbered footnote references" and registered substitution definitions document-wide).
Before docutils 0.22 (Sphinx 7 and 8 here) the lines of a parsed line block have no source info, and Sphinx extracts no message from a translatable node without a source, so a multi-line button could not be translated. Give such lines the source and line of the button's first content line.
docutils puts the system messages of a line's inline markup (an unknown role, or a role found only through the English fallback) beside the line block, so the button fell back to inline text and parsed the text a second time: the message was reported twice, an autonumbered footnote reference failed, and the bars were kept. The messages are now ignored when checking for line blocks; they have already been reported.
chrisjsewell
added a commit
to dipinknair/sphinx-design
that referenced
this pull request
Nov 9, 2026
chrisjsewell
added a commit
that referenced
this pull request
Nov 9, 2026
…ils does The splitter stripped every continuation line, and kept the empty first line of a bare bar. docutils (and so #308's block parse) strips only the common indent of the continuation lines, so they keep their indent relative to each other, and drops a bare bar's empty first line. A continuation line indented deeper than the one before it therefore lost its leading spaces in text, HTML, LaTeX, man and .pot output, and `|` followed by a continuation line gained a leading newline. Both now match main and docutils.
chrisjsewell
added a commit
that referenced
this pull request
Nov 9, 2026
Three comments in the #308 tests still described the removed block parse (nodes moved out of it, messages placed beside the line block, a source fallback for docutils < 0.22). Their assertions are unchanged.
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.
button-linkparsed its body withinline_text, so an RST line block kept the|characters and did not break the lines. Bars indented one column past an option such as:expand:were parsed as a block quote around that line block, which is the markup in #156. Those bars are now separate lines, and a blank line between two bars is handled the same way.button-refuses the same content path.CHANGELOG.mdhas an Unreleased entry for this fix.Fixes #156.
This pull request was drafted with assistance from Cursor. The account owner confirmed it before it was submitted.