Skip to content

Workaround for github-flavored markdown not ignoring newlines within paragraphs#41

Merged
liran-funaro merged 1 commit intoliran-funaro:mainfrom
krobelus:github-markdown
Oct 16, 2025
Merged

Workaround for github-flavored markdown not ignoring newlines within paragraphs#41
liran-funaro merged 1 commit intoliran-funaro:mainfrom
krobelus:github-markdown

Conversation

@krobelus
Copy link

@krobelus krobelus commented Oct 16, 2025

I use sphinx-markdown-builder to generate release notes for GitHub
releases.

Unlike CommonMark, GitHub's flavor of Markdown interprets input like
line1\nline2 as line1<br/>line2.

As a workaround, I could write each paragraph in my *.rst sources in
only one line *.rst. But I'm not sure I want to do that; it would
be surprising to people who work on the *.rst sources because all
other builders (HTML, man, markdown+commonmark) handle this just fine.

Add a workaround to produce a faithful version GitHub-flavored
markdown by joining all multiline paragraphs into a single line.

I'm not aware of significant downsides yet (except that the Markdown
is uglier) but I haven't tested beyond my real-world use.

To be safe, I put it behind a config option, if only to not muddy
the waters as to which dialect of Markdown we are targeting.

Might as well make that option open for extensions, because there
are quite a few flavors:

$ pandoc --list-input-formats | grep mark -i | paste -sd ,
commonmark,commonmark_x,markdown,markdown_github,markdown_mmd,markdown_phpextra,markdown_strict

…paragraphs

I use sphinx-markdown-builder to generate release notes for GitHub
releases.

Unlike CommonMark, GitHub's flavor of Markdown interprets input like
"line1\nline2" as "line1<br/>line2".

As a workaround, I could write each paragraph in my *.rst sources in
only one line *.rst.  But I'm not sure I want to do that; it would
be surprising to people who work on the *.rst sources because all
other builders (HTML, man, markdown+commonmark) handle this just fine.

Add a workaround to produce a faithful version GitHub-flavored
markdown by joining all multiline paragraphs into a single line.

I'm not aware of significant downsides yet (except that the Markdown
is uglier) but I haven't tested beyond my real-world use.

To be safe, I put it behind a config option, if only to not muddy
the waters as to which dialect of Markdown we are targeting.

Might as well make that option open for extensions, because there
are quite a few flavors:

	$ pandoc --list-input-formats | grep mark -i | paste -sd ,
	commonmark,commonmark_x,markdown,markdown_github,markdown_mmd,markdown_phpextra,markdown_strict
@coveralls
Copy link

Pull Request Test Coverage Report for Build 18552270670

Details

  • 3 of 3 (100.0%) changed or added relevant lines in 2 files are covered.
  • No unchanged relevant lines lost coverage.
  • Overall coverage increased (+0.006%) to 98.344%

Totals Coverage Status
Change from base Build 18529202121: 0.006%
Covered Lines: 772
Relevant Lines: 785

💛 - Coveralls

Copy link
Owner

@liran-funaro liran-funaro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@liran-funaro liran-funaro merged commit 7c4daaf into liran-funaro:main Oct 16, 2025
7 checks passed
@krobelus
Copy link
Author

Thanks! I'd appreciate a release so I can use the PyPI package instead of my fork. But no rush.

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.

3 participants