[chrisjsewell]

What and why

Three docs-only changes, one commit each, plus a small wording follow-up:

1. Usage example (Usage example #44).
   The "mdit-py-plugins package" section imported plugin1, plugin2 from mdit_py_plugins, which do not exist:
   each plugin lives in its own submodule and the package only exports __version__.
   It now shows real imports (front_matter, footnote, tasklists), a chain of use calls,
   a keyword option (tasklists_plugin, enabled=True), and says where each plugin's options are documented.
2. dollarmath rendering contract (Document the rendering workflow with dollarmath #111).
   The dollarmath_plugin docstring now lists the HTML each token renders to and the display_mode its renderer gets:
   math_inline is <span class="math inline"> (False); math_inline_double is <div class="math inline"> (True);
   math_block is <div class="math block"> (True); math_block_label is <div id="..." class="math block"> with the anchor first (True).
   The tag carries the display mode and the class records where the math was written, as in markdown-it-dollarmath.
   The renderer parameter now says its return value goes into the element as is,
   so a custom renderer is responsible for escaping it (the default renderer does).
   A new "Rendering dollarmath output" section in docs/index.md shows the two usual workflows:
   a renderer= that adds \(...\) / \[...\] delimiters for MathJax or KaTeX auto-render (escaping with escapeHtml),
   and a browser script that typesets the elements with KaTeX, taking displayMode from el.tagName === "DIV"
   and keeping a labelled block's anchor out of the math.
   It notes that a browser closes the <p> before an inline $$ <div>, so the text after it falls outside the paragraph,
   and points at label_renderer= and md.add_render_rule for changing the anchor, tags or classes.
   This answers Document the rendering workflow with dollarmath #111 with documentation instead of changing the class of inline $$ (the approach of fix: inline double dollar to be rendered with class math block #124),
   which would break parity with markdown-it-dollarmath and make inline $$ indistinguishable from block math.
   To keep the Math section readable, the amsmath autodoc now comes before dollarmath, so the new subsection sits under the plugin it describes.
3. Read the Docs on Python 3.13.
   .readthedocs.yml moves from ubuntu-22.04 / Python 3.10 to ubuntu-24.04 / Python 3.13.
   On 3.10 the rtd extra resolves markdown-it-py 3.0.0, myst-parser 4.0.1 and Sphinx 8.1.3
   (myst-parser 5 needs Python 3.11+), so the published docs were built against an old stack.
   On 3.13 it resolves markdown-it-py 4.2.0, myst-parser 5.1.0, Sphinx 9.2.0 and docutils 0.22.4.

No rendered output changes; the only code-file change is the dollarmath_plugin docstring.

How it was tested

• sphinx-build -nW --keep-going -b html docs/ <out> (the tox -e docs-clean command) on Python 3.13 with .[rtd]:
  green on master before the change, and green on the branch head.
• Every python block in docs/index.md executed as written (a small extractor script, fresh namespace per block),
  on Python 3.13 (markdown-it-py 4.2.0) and Python 3.10 (markdown-it-py 3.0.0): all pass.
  On master the usage block fails with ImportError: cannot import name 'plugin1' from 'mdit_py_plugins'.
• The html block in the new section is byte-identical to what the renderer= example renders.
• The note about <p> and <div> was checked with html5lib (an HTML5 spec parser):
  it closes the <p> before the <div> and leaves " in a paragraph." outside it.
• The KaTeX browser snippet was run under jsdom with KaTeX 0.16.22, against the plugin's default output
  for $a<b$, inline $$x^2$$ (with double_inline=True), a $$ block and a labelled block:
  the span typesets inline, all three divs typeset in display mode, and the label anchor is kept.
  The delimiter workflow was checked the same way with KaTeX's auto-render extension and its default delimiters: same result.
• md.add_render_rule("math_inline", ...) after use(dollarmath_plugin) overrides the default rule (checked).
• pytest: 511 passed (Python 3.13, markdown-it-py 4.2.0).
• pre-commit run --all-files: all hooks pass.

Closes #44
Closes #111

Notes for the reviewer

• converted formula lost its delimiters #60 ("converted formula loses its delimiters") is answered by the renderer= example here; it is not auto-closed by this PR.
• fix: inline double dollar to be rendered with class math block #124 is superseded by this documentation approach and can be closed with a pointer to the new section.
• The RTD change takes effect on the next build of this PR's preview; check it builds green there.
• The amsmath/dollarmath autodoc order swap is the only reordering in the page.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.30%. Comparing base (d11bdaf) to head (d8c2667).
⚠️ Report is 19 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #166      +/-   ##
==========================================
+ Coverage   92.80%   93.30%   +0.49%     
==========================================
  Files          31       40       +9     
  Lines        1835     2285     +450     
==========================================
+ Hits         1703     2132     +429     
- Misses        132      153      +21     

Flag	Coverage Δ
pytests	93.30% <ø> (+0.49%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.