Render "GFM"-likely HTML in Sphinx with MyST-Parser

MyST-Parser is Sphinx extension to parse Markdown document sources. We can write high structured document using it even if we don't know syntax reStructuredText. MyST-Parser supports GFM, but ... MyST-Parser has some options for behavior. 1 There is myst_gfm_only in options. This is to run parse GitHub Flavored Markdown (GFM) that support some extended syntax from Commonmark. But, when this option is True, it does not inject into linefeed of sources. Example Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. This markdown source has line feed each sentence. When Sphinx converts it to HTML by sphinx-build. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. But GitHub render from this source. 2 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Why it happened? GFM is not matched between spec and behavior. GFM spec is put on https://github.github.com/gfm/. There are "6.12Hard line breaks " and "6.13 Soft line breaks" about spec of line breaks. Spec of soft line break: A regular line break (not in a code span or HTML tag) that is not preceded by two or more spaces or a backslash is parsed as a softbreak. (A softbreak may be rendered in HTML either as a line ending or as a space. The result will be the same in browsers. In the examples here, a line ending will be used.) We expect that it renders nothing when there are soft line breaks. But actually, GitHub.com renders tag from line feed. MyST-Parser doesn't have options for line breaks. It is difficult that to adjust for implementation of GitHub? No, you can resolve it by hack class definition. How to hack for realize "actual" GFM style line breaks. Code Please write it code into conf.py of your document. def setup(app): # If you already defined setup, write these code into before `return`. from myst_parser.mdit_to_docutils.base import DocutilsRenderer DocutilsRenderer.render_softbreak = DocutilsRenderer.render_hardbreak Description When Sphinx with MyST-Parser convert from Markdown to HTML, generates intermediate object called "doctree". MyST-Parser parse Markdown and create doctree. Writer process of Sphinx generates HTML from doctree. To create doctree from Markdown, MyST-Parser defines DoctreeRenderer. This class have methods that works each AST nodes of Markdown. DocutilsRenderer.render_softbreak is method to put linefeed code when process visits "soft line breaks". DocutilsRenderer.render_hardbreak is method to put HTML when process visits "hard line breaks". In Python, we can override methods of classes by reassign. Resolve code is to override render_softbreak by render_hardbreak. Therefore, when parser found all line breaks, it runs as "hard line breaks". https://myst-parser.readthedocs.io/en/latest/configuration.html ↩ Actually, tag puts on single line, it added tail of lines. ↩

May 11, 2025 - 20:05

Render "GFM"-likely HTML in Sphinx with MyST-Parser

MyST-Parser is Sphinx extension to parse Markdown document sources.
We can write high structured document using it even if we don't know syntax reStructuredText.

MyST-Parser supports GFM, but ...

MyST-Parser has some options for behavior. ¹
There is myst_gfm_only in options. This is to run parse GitHub Flavored Markdown (GFM) that support some extended syntax from Commonmark.

But, when this option is True, it does not inject into linefeed of sources.

Example

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

This markdown source has line feed each sentence.

When Sphinx converts it to HTML by sphinx-build.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

But GitHub render from this source. ²

Why it happened?

GFM is not matched between spec and behavior.

GFM spec is put on https://github.github.com/gfm/.
There are "6.12Hard line breaks
" and "6.13 Soft line breaks" about spec of line breaks.

Spec of soft line break:

A regular line break (not in a code span or HTML tag) that is not preceded by two or more spaces or a backslash is parsed as a softbreak. (A softbreak may be rendered in HTML either as a line ending or as a space. The result will be the same in browsers. In the examples here, a line ending will be used.)

We expect that it renders nothing when there are soft line breaks.
But actually, GitHub.com renders tag from line feed.

MyST-Parser doesn't have options for line breaks.

It is difficult that to adjust for implementation of GitHub?
No, you can resolve it by hack class definition.

How to hack for realize "actual" GFM style line breaks.

Code

Please write it code into conf.py of your document.

def setup(app):
    # If you already defined setup, write these code into before `return`. 
    from myst_parser.mdit_to_docutils.base import DocutilsRenderer

    DocutilsRenderer.render_softbreak = DocutilsRenderer.render_hardbreak

Description

When Sphinx with MyST-Parser convert from Markdown to HTML, generates intermediate object called "doctree".

MyST-Parser parse Markdown and create doctree.
Writer process of Sphinx generates HTML from doctree.

To create doctree from Markdown, MyST-Parser defines DoctreeRenderer.
This class have methods that works each AST nodes of Markdown.

DocutilsRenderer.render_softbreak is method to put linefeed code when process visits "soft line breaks".
DocutilsRenderer.render_hardbreak is method to put HTML when process visits "hard line breaks".

In Python, we can override methods of classes by reassign.
Resolve code is to override render_softbreak by render_hardbreak.

Therefore, when parser found all line breaks, it runs as "hard line breaks".

https://myst-parser.readthedocs.io/en/latest/configuration.html ↩
Actually, tag puts on single line, it added tail of lines. ↩