Fix: Preserve newlines in code blocks with github flavor#53
Open
yeoldegrove wants to merge 1 commit into
Open
Conversation
Commit 7c4daaf introduced a workaround for GitHub-flavored markdown treating newlines as <br/> in paragraphs by unconditionally replacing all \n with spaces when markdown_flavor='github'. However, this broke code blocks, doctest blocks, and math blocks where newlines are semantically significant. The visit_literal_block method already sets escape_text=False to signal verbatim contexts. This fix conditions the newline replacement on escape_text=True, so newlines are only collapsed in prose paragraphs, not in code/math/comment blocks. Impact: Multi-line argparse usage text (e.g., from sphinxcontrib-autoprogram) now renders correctly with proper line breaks instead of collapsing into a single line with multiple spaces. Added test case with multi-line code block to prevent regression. Signed-off-by: Eike Waldt <waldt@b1-systems.de> On-behalf-of: SAP <eike.waldt@sap.com>
yeoldegrove
force-pushed
the
fix/github_newline
branch
from
May 12, 2026 09:53
4a97e5a to
23a5bf7
Compare
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.
Summary
Fixes a bug where
markdown_flavor = "github"unconditionally collapses all newlines into spaces, breaking multi-line content in code blocks, doctest blocks, math blocks, and comments.Problem
Commit 7c4daaf introduced a workaround for GitHub-flavored markdown treating newlines as
<br/>in paragraphs. However, the implementation invisit_Text()unconditionally replaces all\ncharacters with spaces whenmarkdown_flavor == "github", including text insideliteral_blocknodes (fenced code blocks) where newlines are semantically required.Example Impact
Multi-line argparse usage text from
sphinxcontrib-autoprogram:Before (broken):
usage: command [-h] [--option1 VALUE1] [--option2 VALUE2] [--option3 VALUE3] argumentAfter (fixed):
Root Cause
The
visit_Textmethod intranslator.py:349only checkedself.config.markdown_flavorwithout considering whether the translator was inside a verbatim context.The
visit_literal_blockmethod already pushes a status withescape_text=Falseto signal "we're inside a verbatim block", but this flag was not being checked.Solution
Add
and self.status.escape_textto the condition on line 349:This ensures newlines are only collapsed in normal prose paragraphs (where
escape_text=True), not in code/math/comment blocks (whereescape_text=False).