🔧 Clarify that add_render_rule's name must match a token type

[hikmetba-bit]

Summary

Fixes #308.

MarkdownIt.add_render_rule's docstring gave no indication of what name should be, which led to confusion (as described in the issue): a rule silently never fires if name doesn't match a token's .type, since RendererHTML.render/renderInline just do self.rules.get(token.type, ...).

Why not the suggested runtime warning?

The issue suggests logging a warning when name isn't a "preset rule". I implemented and tested that first, but self.renderer.rules (populated in RendererHTML.__init__ via inspect.getmembers) only contains methods for token types that already have a dedicated renderer method (e.g. fence, code_inline, image). Most token types — paragraph_open, heading_open, etc. — have no such method and fall back to the generic renderToken, so they're simply not keys in that dict.

That means a name not in self.renderer.rules check produces a false warning for the single most common use of this method: adding a custom renderer for a standard token type that didn't previously have a dedicated one (verified with a quick test: md.add_render_rule("paragraph_open", ...) would warn even though "paragraph_open" is a perfectly valid token type). There's also no other registry of "valid" token type names to check against, since plugins are free to introduce their own.

Given that, documenting the actual contract (name must equal a token's .type) is the fix that resolves the reported confusion without adding noisy false positives. Happy to revisit a runtime check if maintainers have a different validation approach in mind.

Test plan

• Ran pytest tests/test_api/test_main.py before and after: 20 passed both times (2 pre-existing unrelated failures due to the optional linkify-it-py dependency not being installed in this sandbox).
• Docs-only change to a docstring, no behavior change, so no new test was added.

🤖 Generated with Claude Code

[chrisjsewell]

Cheers