📚 DOCS: Document renderer constructor differences

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)

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}

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