Skip to content

Commit 879f397

Browse files
committed
📚 DOCS: make the section_ref grammar normative
State the grammar in the plugin docstring as rules: ASCII digits only, the ASCII-letter look-ahead (a non-ASCII letter does not block a match), no trailing dot, the nine-digit bound, the contexts where no reference forms, and that \§ is not a backslash escape (the backslash stays visible), with § and § giving a literal sign. Pin the statements the fixtures did not cover yet with fixture rows: non-ASCII digits, the two entities, an autolink and raw HTML. Note that markdown-it-py's renderInlineAsText keeps only text tokens, so a renderer that wants the reference in image alt text should use the section_ref token's content.
1 parent 098895a commit 879f397

2 files changed

Lines changed: 58 additions & 13 deletions

File tree

‎mdit_py_plugins/section_ref/index.py‎

Lines changed: 30 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -41,19 +41,32 @@
4141
def section_ref_plugin(md: MarkdownIt) -> None:
4242
"""Parse section-sign references such as ``§1``, ``§1.1`` and ``§2.3.4``.
4343
44-
A reference is a ``§`` immediately followed by ASCII digits, optionally
45-
grouped into further ``.``-separated levels (no spaces are allowed).
46-
A trailing dot is not consumed, so ``see §1.`` captures ``§1``. A ``§``
47-
directly followed by an ASCII letter (e.g. ``§1a``) is *not* a reference,
48-
but a following non-ASCII letter does not block a match, so ``见§3章``
49-
still captures ``§3``. A reference with any level longer than nine
50-
digits (e.g. ``§1.1234567890``) is not a reference either: the whole
51-
text stays literal, rather than a shorter prefix being captured.
52-
Leading zeros count towards the nine digits, so ``§0000000001`` stays
53-
literal too.
54-
Following CommonMark backslash-escape behaviour, ``\\§1`` stays literal
55-
text, while ``\\\\§1`` renders a literal backslash followed by a live
56-
reference.
44+
The grammar is normative:
45+
46+
- A reference is ``§`` (U+00A7) immediately followed by one or more
47+
``.``-separated levels, with no spaces.
48+
Each level is 1 to 9 ASCII digits, ``§([0-9]{1,9}(\\.[0-9]{1,9})*)``,
49+
and the match is maximal.
50+
Only ASCII ``0``-``9`` are digits: other Unicode digits, such as
51+
Arabic-Indic (U+0660 to U+0669) or fullwidth (U+FF10 to U+FF19) digits,
52+
do not form a reference, so a ``§`` followed by one stays literal text.
53+
- A trailing ``.`` is not part of the reference,
54+
so in ``see §1.`` the reference is ``§1`` and the ``.`` stays text.
55+
- There is no reference, and the whole run stays literal text,
56+
if the character after the match is an ASCII letter (``§1a``, ``§1.2b``),
57+
or if any level has more than nine digits, counting leading zeros
58+
(``§1234567890``, ``§0000000001``).
59+
No shorter prefix is taken, so ``§1.1234567890.2`` stays literal too.
60+
A non-ASCII letter after the match does not block it,
61+
so ``见§3章`` captures ``§3``.
62+
- References are recognised wherever inline text is parsed,
63+
and not inside code spans, autolinks, raw HTML or inline math.
64+
- ``\\§`` is not a CommonMark backslash escape,
65+
because ``§`` is not ASCII punctuation:
66+
in ``\\§1`` the backslash stays visible and no reference is formed.
67+
``\\\\§1`` is a literal backslash followed by the reference ``§1``.
68+
To write a literal sign, use ``§`` or ``§``,
69+
which never form a reference (``§1`` renders as the text ``§1``).
5770
5871
Each reference becomes a single ``section_ref`` leaf token
5972
(``nesting=0``, ``children=None``, ``tag=""``, ``attrs={}``),
@@ -66,6 +79,10 @@ def section_ref_plugin(md: MarkdownIt) -> None:
6679
6780
The default rendering is ``<span class="section-ref">§1.1</span>``.
6881
Override it with ``md.add_render_rule("section_ref", ...)``.
82+
markdown-it-py's ``renderInlineAsText``, which renders image ``alt`` text,
83+
keeps only ``text`` tokens, so ``![a §7 b](x.png)`` renders ``alt="a b"``
84+
(as it does for inline math). A renderer that wants the reference in the
85+
alt text should use the ``section_ref`` token's ``content``.
6986
7087
.. versionadded:: 0.7.0
7188

‎tests/fixtures/section_ref.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,20 @@ Inside inline code (not captured):
8383
<p><code>§1</code></p>
8484
.
8585

86+
Inside an autolink (not captured):
87+
.
88+
<https://example.com/§1>
89+
.
90+
<p><a href="https://example.com/%C2%A71">https://example.com/§1</a></p>
91+
.
92+
93+
Inside raw HTML (not captured), but captured in its content:
94+
.
95+
<span title="§1">§2</span>
96+
.
97+
<p><span title="§1"><span class="section-ref">§2</span></span></p>
98+
.
99+
86100
Inside fenced code block (not captured):
87101
.
88102
```
@@ -135,13 +149,27 @@ Escaped backslash before ref (captured):
135149
<p>\<span class="section-ref">§1</span></p>
136150
.
137151

152+
Entity section signs give a literal sign (not captured):
153+
.
154+
&sect;1 and &#167;2
155+
.
156+
<p>§1 and §2</p>
157+
.
158+
138159
Followed by non-digit, non-space char (not captured):
139160
.
140161
§x and §.5
141162
.
142163
<p>§x and §.5</p>
143164
.
144165

166+
Non-ASCII digits (not captured):
167+
.
168+
§١ and §3
169+
.
170+
<p>§١ and §3</p>
171+
.
172+
145173
Leading zeros preserved in content (meta numbers are normalized):
146174
.
147175
§01.02

0 commit comments

Comments
 (0)