Skip to content

Fix: Preserve newlines in code blocks with github flavor#53

Open
yeoldegrove wants to merge 1 commit into
liran-funaro:mainfrom
yeoldegrove:fix/github_newline
Open

Fix: Preserve newlines in code blocks with github flavor#53
yeoldegrove wants to merge 1 commit into
liran-funaro:mainfrom
yeoldegrove:fix/github_newline

Conversation

@yeoldegrove

Copy link
Copy Markdown

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 in visit_Text() unconditionally replaces all \n characters with spaces when markdown_flavor == "github", including text inside literal_block nodes (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]                  argument

After (fixed):

usage: command [-h] [--option1 VALUE1]
               [--option2 VALUE2]
               [--option3 VALUE3]
               argument

Root Cause

The visit_Text method in translator.py:349 only checked self.config.markdown_flavor without considering whether the translator was inside a verbatim context.

The visit_literal_block method already pushes a status with escape_text=False to signal "we're inside a verbatim block", but this flag was not being checked.

Solution

Add and self.status.escape_text to the condition on line 349:

# Before:
if self.config.markdown_flavor == "github":
    text = text.replace("\n", " ")

# After:
if self.config.markdown_flavor == "github" and self.status.escape_text:
    text = text.replace("\n", " ")

This ensures newlines are only collapsed in normal prose paragraphs (where escape_text=True), not in code/math/comment blocks (where escape_text=False).

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
yeoldegrove force-pushed the fix/github_newline branch from 4a97e5a to 23a5bf7 Compare May 12, 2026 09:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant