From 06da43a5aee6c8497c07bca9ce23674163d3f655 Mon Sep 17 00:00:00 2001 From: hikmetba-bit Date: Wed, 16 Sep 2026 20:39:07 +0300 Subject: [PATCH] Clarify that add_render_rule's name must match a token type Fixes #308. The docstring gave no indication of what `name` should be, which led to confusion (see the issue): a rule silently never fires if `name` doesn't match a token's `.type`, since the renderer just looks up `self.rules.get(token.type, ...)`. A runtime warning was considered (as suggested in the issue), but `self.renderer.rules` only contains methods for token types that already have a dedicated renderer method (e.g. `fence`, `code_inline`). Most token types (`paragraph_open`, `heading_open`, ...) fall back to the generic `renderToken` and are simply not keys in that dict, so "name not in self.renderer.rules" would produce 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 one. There is no other registry of "valid" token type names to check against, since plugins are free to introduce new token types. Documenting the actual contract is the fix that doesn't add noise. Co-Authored-By: Claude Sonnet 5 --- markdown_it/main.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/markdown_it/main.py b/markdown_it/main.py index 87835e54..050a3b87 100644 --- a/markdown_it/main.py +++ b/markdown_it/main.py @@ -228,6 +228,11 @@ def add_render_rule( """Add a rule for rendering a particular Token type. Only applied when ``renderer.__output__ == fmt`` + + :param name: must equal the ``type`` of the token(s) this should render + (e.g. ``"heading_open"``, ``"fence"``); it is not an arbitrary label. + If it does not match any token type actually produced by the active + rules, ``function`` will silently never be called. """ if self.renderer.__output__ == fmt: self.renderer.rules[name] = function.__get__(self.renderer) # type: ignore