Skip to content

Detect markdown-style code fences - #172

Open
Eljees wants to merge 3 commits into
sphinx-contrib:mainfrom
Eljees:detect-markdown-code-fences
Open

Eljees wants to merge 3 commits into
sphinx-contrib:mainfrom
Eljees:detect-markdown-code-fences

Conversation

@Eljees

@Eljees Eljees commented Aug 14, 2026

Copy link
Copy Markdown

Fixes #155.

A markdown-style fenced code block is rendered as plain text by Sphinx without any warning, so
the mistake is only visible in the built HTML.

check_triple_backticks covers the inline form only (its regex requires text between the
fences), so a line made of fences is not covered by anything. This adds a markdown-code-fence
checker for it. Only the opening fence of a block is reported, so a fenced block gives one
error rather than two.

Two things worth a look during review

The checker is rst_only (the decorator default), so it sees the output of
hide_non_rst_blocks() and never looks inside literal blocks or code-block directives.
Documentation that shows markdown on purpose therefore stays quiet.

A backtick is a valid section title adornment character, so a line of backticks under (or over)
a title is indistinguishable from a fence by shape alone. _is_section_adornment() handles
that: a line made only of backticks is left alone when it is adjacent to a line of text no
longer than itself. Without that guard your own xpass/sections.rst and
xpass/this-is-just-a-title.rst fixtures fail.

Measured

On c6d82b7:

result
baseline, clean tree 110 passed, 1 skipped, 0 failed
new fixture, before the fix 1 failed (nothing reported)
full suite, after the fix 111 passed, 1 skipped, 0 failed
the 639 .rst files shipped in the docutils 0.23 and Sphinx 8.1.3 sdists 0 reports
the same 639 files, with _is_section_adornment() removed 53 reports, all of them title adornments

The test is tests/fixtures/xfail/markdown-code-fence.rst, picked up automatically by
gather_xfail(); it fails on an unpatched checkout.

ruff check and ruff format --diff at the pinned v0.15.20 are clean on both changed files.

AI-assisted (LLM used for drafting); the runs above are mine.

Sphinx renders a fenced code block as plain text without emitting any warning, so the mistake is silent in the built HTML.

A backtick is a valid section title adornment character, so a line made only of backticks is only reported when it is not adjacent to a shorter-or-equal line of text.

Closes sphinx-contrib#155

@m-aciek m-aciek left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Looks good to me 👍

@Eljees

This comment was marked as resolved.

@hugovk hugovk closed this Sep 21, 2026
@hugovk hugovk reopened this Sep 21, 2026
@hugovk

This comment was marked as resolved.

@Eljees

This comment was marked as resolved.

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.

Cannot detect markdown-style code block (```)

3 participants