liran-funaro / sphinx-markdown-builder / 43207910179

100%

push

github

Escape Markdown syntax characters in plain text (#130)

## Summary

`ESCAPE_RE` only escaped `\`, `*`, `` ` `` and a word-leading `_`. Plain
text that looks like Markdown syntax therefore rendered as headings,
lists, quotes, links or HTML tags.

Two simple regexes now do the escaping:

- **`ESCAPE_RE`**: main's original pattern, plus `[`, `]` and `<`
anywhere, and a `#`, `>`, `+` or `-` at the start of a line. It puts `\`
before the matched character (`r"\\\1"`). Escaping the first character
also covers `## x` and `---`. An extra `\` (for example on `#42`)
renders the same, since `\` before ASCII punctuation is always a valid
CommonMark escape.
- **`ORDERED_LIST_RE`**: the `.` or `)` of an ordered-list marker (`1.
`, `2) `). It needs its own regex because the backslash goes after the
digits (`1\.`). It only matches when a space or the line end follows, so
numbers such as the table cell `1.10` are left alone.

Link, anchor and image syntax is written by the translator through
`add()`, not through `Text` nodes, so it is not affected. No existing
golden file changed.

I added the `2)` marker because CommonMark treats it as an ordered list,
the same as `1.`.

## What the fixture tests

The fixture is text as users write it, with no RST escapes.
reStructuredText removes a backslash escape, so `\#` and `#` give the
same doctree (`<paragraph># ...`), and the HTML builder renders both as
`#`. The Markdown output `\#` renders as `#` too, matching HTML. RST
itself would turn a paragraph starting with `1.`, `2)`, `+` or `-` into
a list. Those markers are therefore placed on the continuation lines of
a paragraph, where RST keeps them as plain text.

## Before / after

Input (new fixture section in `tests/source/blocks.rst`):

```rst
# not a heading

> not a quote

Text with [brackets](not a link) and List<int>.

reStructuredText would start a list at these markers, but not on the continuation lines of a paragraph:
1. not a list
2) not a list
+ not a list
- 5 degr... (continued)

4 of 4 new or added lines in 1 file covered. (100.0%)

798 of 798 relevant lines covered (100.0%)

4.0 hits per line