From 935bc0f41bed85f78cca24ec0895c34e2aec34fa Mon Sep 17 00:00:00 2001 From: jf nz Date: Sun, 6 Sep 2026 08:52:57 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20DOCS:=20Document=20renderer=20co?= =?UTF-8?q?nstructor=20differences?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 4 ++++ docs/using.md | 6 ++++++ markdown_it/port.yaml | 6 ++++++ 3 files changed, 16 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d50cb3e..e9bd6057 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Change Log +## Unreleased + +* 📚 Document the Python renderer constructor contract. + ## 4.2.0 - 2026-05-07 * ✨ Add `make_fence_rule()` factory for configurable fence markers in [#394](https://github.com/executablebooks/markdown-it-py/pull/394) diff --git a/docs/using.md b/docs/using.md index 507f49c1..70e31c31 100644 --- a/docs/using.md +++ b/docs/using.md @@ -333,6 +333,12 @@ md = MarkdownIt("commonmark", renderer_cls=MyRenderer) md.render("*a*") ``` +`MarkdownIt` creates the renderer by calling `renderer_cls(self)`, passing the parser instance as a positional argument. +This differs from JavaScript, where the renderer is constructed with no arguments. +If you override `__init__` in a custom renderer, it must accept this parser argument; when subclassing `RendererHTML`, call `super().__init__(parser)` to initialise the render rules. +`RendererHTML` itself accepts an optional `parser=None` argument and does not use or store it, so `RendererHTML()` is also valid when rendering tokens directly. +The example above inherits this constructor unchanged. + Plugins can support multiple render types, using the `__output__` attribute (this is currently a Python only feature). ```{jupyter-execute} diff --git a/markdown_it/port.yaml b/markdown_it/port.yaml index ce2dde95..00da22e0 100644 --- a/markdown_it/port.yaml +++ b/markdown_it/port.yaml @@ -35,6 +35,12 @@ use `MarkdownIt("commonmark", {"html": False})` instead of `MarkdownIt({"html": False})` - The default configuration preset for `MarkdownIt` is "commonmark" not "default" - Allow custom renderer to be passed to `MarkdownIt` + - | + `MarkdownIt` constructs its renderer with `renderer_cls(self)`, passing the + parser instance as a positional argument; JavaScript constructs its renderer + with no arguments. Custom renderer constructors must accept this argument. + `RendererHTML` accepts an optional `parser=None` argument but does not use it, + so it can also be instantiated directly without a parser. - | change render method signatures `func(tokens, idx, options, env, slf)` to