Skip to content



Feature Add a pre-commit hook for pydoc-markdown.298@RomainTT
Improvement Bump minimum version of `databind.core` and `databind.json` to `^4.4.2` to ensure Python 3.12 support304@NiklasRosenstein
Breaking change Drop Python 3.7 compatibility304@NiklasRosenstein
Fix Fix `escape_except_blockquotes` option for greater than 9 blockquotes in a docstring317@jackgerrits

4.8.2 (2023-06-26)

Fix Fix key aliases for `pre-render` and `post-render` keys in `Hooks` configuration295291@NiklasRosenstein

4.8.1 (2023-06-21)

Improvement Improve error message when no Pydoc Markdown configuration is found293@NiklasRosenstein
Fix Upgrade to Databind `^4.4.0` which fixes the "`ForwardRef` cannot be parameterized" error.294292@NiklasRosenstein
Fix Fix `NoMatchingConverter` for `TypeHint(typing.List[~T_Page])` by making the `Page` type a concrete subclass of the old `Page` class now called `GenericPage`. This is needed to correctly define a recursive type that Databind can de/serialize. The `Page` type stays backwards compatible at runtime for cases when it is used as a generic (e.g. `class MyPage(Page[MyPage]):`) to not break existing code.294291@NiklasRosenstein
Tests Add unit tests to deserialize Mkdocs and Hugo example configuration.294@NiklasRosenstein

4.8.0 (2023-05-28)

Improvement Upgrade from Databind `^1.5.0` to ^4.3.0`. This should not have any impact on the average Pydoc-Markdown user, however there may be some changes necessary for users that have been using the Pydoc-Markdown API beacuse of the changes to Databind between v1 and v4. However, these users should have pinned the major version of databind they're relying on, so this change is not considered breaking for Pydoc-Markdown.289@NiklasRosenstein

4.7.0 (2023-05-28)

Improvement Change `PythonLoader.encoding` default value from `None` (system default) to `utf-8`282@NiklasRosenstein
Improvement Support parsing all types of docstring formats that are supported by the `docstring_parser` module in `SphinxProcessor`, not just ReST282@hippalectryon-0
Fix No longer HTML-escape text in Markdown code blocks.282@hippalectryon-0
Fix Fix codeblocks rendering to maintain indentation as per the original docstring.283169@hippalectryon-0
Improvement Allow Pyyaml `^6.0` in addition to `^5.0`287@NiklasRosenstein
Improvement Undeprecated YAML-based configuration for Pydoc-Markdown.288286@NiklasRosenstein
Docs Update docs to inform user that `mkdocs` with `mkdocs-material` must be installed in Novella Usage guide.270@NiklasRosenstein

4.6.4 (2022-11-13)

Improvement add explicit compatibility with Novella 0.2.x (`>=0.1.10,<0.3.0`)@NiklasRosenstein
Docs Fix installation instructions using Pipx (#256)256@NiklasRosenstein
Fix fix interpreting Markdown in-document anchor links as cross references274@NiklasRosenstein
Fix fix generated code for class signature with not base class and a metaclass parameter272@NiklasRosenstein

4.6.3 (2022-03-13)

Fix fix subscript error for type annotation in Python <=3.8@NiklasRosenstein

4.6.2 (2022-03-13)

Fix fix AttributeError when using a Git source linker with `use_branch` disabled252250@NiklasRosenstein
Hygiene remove unused functions that interact with Git since the same functionality from the `nr.utils.git` module is used instead now252@NiklasRosenstein

4.6.1 (2022-03-05)

Fix fix recognition of overwritten values in `MarkdownRenderer.header_level_by_type`249248@NiklasRosenstein
Fix fix backwards compat of handling `"Data"` key in `MarkdownRenderer.header_level_by_type` when now it should be `"Variable"`249@NiklasRosenstein

4.6.0 (2022-03-02)

Docs docusaurus: Update `plugin-content-docs` config for docusarus@beta to not exclude files and folders with underscores.235189@chrisstetter
Hygiene remove `MarkdownRenderer.classdef_render_init_signature_if_needed` option because it never worked to begin with245@NiklasRosenstein
Breaking change remove `MarkdownRenderer.render_to_stream()` from public api245@NiklasRosenstein
Feature add `pydoc_markdown.interfaces.SingleObjectRenderer` and use it in Novella `@pydoc` tag processor245@NiklasRosenstein
Feature add `ApiSuite` class and `ResolverV2` which is used by the new `@pydoc` tag preprocessor when using Novella245@NiklasRosenstein
Feature `MarkdownReferenceResolver` now implements the new `ResolverV2` interface and can resolve references globally245@NiklasRosenstein
Feature `CrossRefProcessor` now accepts a `resolver_v2` argument to use instead of the `resolver` object passed through the `Processor` API245@NiklasRosenstein
Feature bring back formatting function, class and variable signatures with YAPF. (Tagging @lgeiger as the author because he was the original author of the feature in a previous version of Pydoc-Markdown, see
Fix fix forwarding of `PluginBase.init()` calls to sub-plugins in unittests and `DocusaurusRenderer`245@NiklasRosenstein
Improvement do not render link to source for modules in `MarkdownRenderer`245@NiklasRosenstein
Improvement Git source linkers now fall back to the SHA if the current branch is invalid (e.g. in a detached HEAD state) and logs a warning@NiklasRosenstein

4.5.1 (2022-02-28)

Fix hugo: Hugo now respects the baseUrl option @Heiss@NiklasRosenstein
Docs docusaurus: Update `plugin-content-docs` config for docusarus@beta to not exclude files and folders with underscores.189@chrisstetter
Fix hugo: Adds Apple Silicon to Hugo's recognized architectures.@MilesCranmer
Fix databind >1.4.0 changed Location.format()246@NiklasRosenstein

4.5.0 (2021-12-12)

Feature MarkdownRenderer: Add `render_page_title` option.214, 216@t6847kimo
Feature git: Git source linkers now have a `use_branch` option to use the current branch name instead of the current commit SHA when generating links to the source code218@NiklasRosenstein

4.4.0 (2021-12-12)

Fix Sphinx processor now triggers when `:arg` or other Sphinx keywords are encountered in a docstring221@NiklasRosenstein
Tests Refactor sphinx processor tests and add new test for param keyword only. Fixes minor issue with argument only docstring. @gmarks2149@NiklasRosenstein
Fix sphinx_processor: Fix multi-line parameter sphinx docstring rendering issue by switching to docstring-parser to parse the docstrings. @gmarks2149195@NiklasRosenstein
Fix Fix configuration generated with `--bootstrap mkdocs`230@gethvi
Feature HugoRenderer: add `serverURL` and `serverPort` options to `$.renderer.config` block to allow overwriting the URL where the local Hugo server serves from202, 231@melMass
Feature add `GitlabSourceLinker` class (entrypoint name: `gitlab`). @Heiss@NiklasRosenstein
Feature MarkdownRenderer: add `render_typehint_in_data_header` option to `MarkdownRenderer`229@NiklasRosenstein
Fix MarkdownRenderer: no longer escape markdown in headers when `html_headers` is enabled (used to result in additional backslashes when interpreted by most Markdown to HTML renderers)@NiklasRosenstein

4.3.2 (2021-09-04)

Fix minimum `click` version is `7.1`, allow also `8.x`@NiklasRosenstein

4.3.1 (2021-09-01)

Fix Calling pydoc-markdown with `--render-toc` option causes an exception213@NiklasRosenstein

4.3.0 (2021-08-28)

Fix fix use of `docspec.ApiObject.path` after we migrated away from using deprecated `docspec.ReverseMap`@NiklasRosenstein
Improvement change default configuration of `MarkdownRenderer` (`signature_with_vertical_bar = False` (many people seemed to dislike that) and `signature_with_def = True` (for consistency with the included `class` keyword for classes))@NiklasRosenstein

4.2.0 (2021-08-20)

Fix HugoRenderer: Enable Hugo `markup.goldmark.renderer.unsafe` option by default198@NiklasRosenstein
Fix MarkdownRenderer: Markdown renderer produces header anchors with `name` attribute instead of `id`200@NiklasRosenstein
Feature MarkdownRenderer: @melMass added the `MarkdownRenderer.add_module_prefix` option199@NiklasRosenstein
Docs switch Pydoc-Markdown to generated its docs with MkDocs@NiklasRosenstein
Docs add Jinja2 renderer documentation in generated docs@NiklasRosenstein
Improvement update template for `--bootstrap readthedocs` and related documentation@NiklasRosenstein
Fix fix `mkdocs` bootstrap configuration, update mkdocs and hugo bootstrap config to include example on how to select parts of the API docs@NiklasRosenstein

4.1.6 (2021-08-09)

Fix HugoRenderer: Restore old behaviour for `HugoConfig.additional_options`, which should be deserialized flat (i.e. it takes on any additional options in the same object that can not be mapped to any other fields of the config object)@NiklasRosenstein

4.1.5 (2021-08-04)

Fix fix import from `databind.core`@NiklasRosenstein

4.1.4 (2021-08-04)

Fix remove unused dependency on `nr.collections`@NiklasRosenstein
Improvement Use `tempfile` instead of `nr.fs`@NiklasRosenstein

4.1.3 (2021-07-24)

Fix MarkdownRenderer: Remove zombie line that triggers error when using the Markdown renderer directly196@NiklasRosenstein

4.1.2 (2021-07-23)

Fix fix `--render-toc` option@NiklasRosenstein
Feature Jinja2Renderer: add `blockquote` and `describe` built-in filters@NiklasRosenstein

4.1.1 (2021-07-22)

Improvement Jinja2Renderer: added `format_function_signature` filter@NiklasRosenstein

4.1.0 (2021-07-22)

Fix CrossrefProcessor: missing trailing characters for unresolved crossref@NiklasRosenstein
Improvement MarkdownRenderer: add MarkdownReferenceResolver helper class@NiklasRosenstein
Feature Add `jinja2` renderer@NiklasRosenstein

4.0.1 (2021-07-22)

Fix fix Python version classifiers@NiklasRosenstein

4.0.0 (2021-07-22)

Breaking change Migrate to `databind.core 1.x` and `databind.json 1.x` from `nr.databind.core` and `nr.databin.json` and uses of `nr.interface` are replaced with ABCs. If you developed plugins for Pydoc-Markdown, please follow the guide at @NiklasRosenstein
Fix docusaurus: Insert an additional newline after header anchors (``) when `MarkdownRenderer.insert_header_anchors` is enabled to fix Docusaurus header rendering. @NiklasRosenstein
Fix unset `__PYENV_LAUNCHER__` environment variable for commands invoked via `$.hooks.pre-render` and `$` to avoid issues when the hook invokes a script installed into a different Python virtualenv than the virtualenv that is currently active in the terminal@NiklasRosenstein
Improvement Pydoc-Markdown now requires Python 3.7 or newer (before it was 3.6 or newer). This is due to `databind.core` having that minimum version requirement@NiklasRosenstein

3.14.0 (2021-07-19)

Feature add `MarkdownRenderer.signature_with_vertical_bar` option (contributed by @t6847kimo)192@NiklasRosenstein

3.13.0 (2021-05-29)

Improvement upgrade to `docspec-python~0.2.0`@NiklasRosenstein

3.12.1 (2021-05-21)

Fix add missing `dataclasses` dependency for Python 3.6 compatibility@NiklasRosenstein
Fix set minimum Python version in `package.yml` to `^3.6`@NiklasRosenstein

3.12.0 (2021-05-21)

Feature SphinxProcessor: parse `type` and `rtype`157@NiklasRosenstein

3.11.0 (2021-05-20)

Feature Add support for getting configuration from pyproject.toml under the [tool.pydoc-markdown] table@NiklasRosenstein
Fix fix docstring in PydocmdPreprocessor@NiklasRosenstein

3.10.3 (2021-05-09)

Fix sort sidebar items in docusaurus183@NiklasRosenstein
Fix replace backslashes with forward slashes in docusaurus sidebar (actually in 3.10.2)129@NiklasRosenstein

3.10.1 (2021-04-02)

Fix fix code blocks indentation in `SphinxProcessor`179@NiklasRosenstein

3.10.0 (2021-02-20)

Feature add `PythonLoader.encoding` option@NiklasRosenstein

3.9.0 (2020-12-15)

Fix Fix `IndexError` while processing short module path (by @g6123)167@NiklasRosenstein
Improvement bump `watchdog` dependency to `^1.0.0`@NiklasRosenstein

3.8.0 (2020-11-06)

Feature add new `bitbucket` source linker (@hkenny, #163)@NiklasRosenstein

3.7.0 (2020-11-05)

Improvement FilterProcessor: Fix `NameError: name _check is not defined`, slightly alter behaviour of `FilterProcessor.expression` field`161@NiklasRosenstein

3.6.1 (2020-11-03)

Fix Fix using `data_code_block` option in `MarkdownRenderer`, and add a unit test for it160@NiklasRosenstein

3.6.0 (2020-10-28)

Feature Add `git` and `gitea` source linker (@tboulogne, #158)@NiklasRosenstein
Improvement Update Docusaurus sidebar generation (@m-vdb, #156)@NiklasRosenstein

3.5.0 (2020-09-04)

Feature docusaurus: Add new `docusaurus` Renderer (contributed to by @m-vdb)151, 147@NiklasRosenstein
Improvement markdown: Remove `MarkdownRenderer.fp` option, add `MarkdownRenderer.render_to_stream()`@NiklasRosenstein
Feature filter: add `FilterProcessor.skip_empty_modules` option@NiklasRosenstein
Feature markdown: Add `MarkdownRenderer.render_module_header_template` and `.escape_html_in_docstring` options@NiklasRosenstein
Feature cli: Add `--bootstrap docusaurus` option@NiklasRosenstein

3.4.0 (2020-08-31)

Feature mkdocs: add `server_port` option, treat `MKDOCS_PORT` environment variable if `server_port` option is not set148@NiklasRosenstein

3.3.1 (2020-08-29)

Fix markdown: Fix "list" object has no attribute "values" in `MarkdownRenderer`149@NiklasRosenstein

3.3.0 (2020-07-17)

Feature plugin types can now be resolved by their FQN (i.e. the absolute import name, such as `pydoc_markdown.contrib.loaders.python.PythonLoader`) in addition to their registered entrypoint name.131@NiklasRosenstein
Feature add new `SourceLinker` interface@NiklasRosenstein
Feature add `GitHubSourceLinker` class (entrypoint name: `github`)@NiklasRosenstein
Feature markdown: add `MarkdownRenderer.source_linker`, `.source_position` and `.source_format` options122@NiklasRosenstein
Improvement cli: `-v,--verbose` and `-q,--quiet` flags are now countable (e.g. `-vv` will raise the logging verbosity to `DEBUG`)@NiklasRosenstein
Improvement internal: Ensure consistency independent of the CWD from which Pydoc-Markdown is invoked as long as the same configuration file is used by introduce the `Context` object and the `init()` method for plugins. The `` is set to the parent directory of the `pydoc-markdown.yml` configuration file. Plugins use that directory to interpret relative paths instead of the current working directory. @NiklasRosenstein
Feature implement YTT-like YAML preprocessing when the Pydoc-Markdown configuration is loaded@NiklasRosenstein

3.2.0.post1 (2020-07-15)

Fix packaging: add `$.readme` to `pydoc-markdown/package.yaml`, fixing the generated `` to include the `` from the parent folder.130@NiklasRosenstein

3.2.0 (2020-07-13)

Feature cli: add `--dump` and `--with-processors/--without-processors` options@NiklasRosenstein
Docs add docstrings to classes defined in `pydoc_markdown.contrib.processors`@NiklasRosenstein
Improvement use `docspec` module instead of `pydoc_markdown.reflection` to represent API objects@NiklasRosenstein
Improvement python: use `docspec-python` to load Python API objects@NiklasRosenstein
Improvement crossref: warnings produced about references that cannot be resolved are now summarized in a single log-line@NiklasRosenstein
Improvement With the removal of `pydoc_markdown.reflection`, the `ModuleGraph` class has also been removed and replaced by List[docspec.Module]`@NiklasRosenstein
Improvement filter: Rename FilterProcessor.include_root_objects to .do_not_filter_modules@NiklasRosenstein
Improvement change type signatures and some method names of interfaces in `pydoc_markdown.interfaces`@NiklasRosenstein
Improvement utils: The `Page.filtered_modules()` method now warns if an element in `Page.contents` did not match an API object@NiklasRosenstein
Fix markdown: the Markdown header level for methods is now correctly read from the "Method" key in `MarkdownRenderer.header_level_by_type`121@NiklasRosenstein
Improvement cli: remove `--bootstrap-mkdocs` in favor of `--bootstrap` option which now accepts an argument@NiklasRosenstein
Improvement cli: the `--bootstrap` option now requires an argument, which must be either "base", "mkdocs" or "hugo" (new)@NiklasRosenstein
Feature mkdocs: The `MkdocsRenderer.clean_render` option is enabled again by default, but instead of removing the whole `content_directory`, it will instead only remove files that it has previously generated (it will place a `.generated-files.txt` file in the `output_directory` for that).@NiklasRosenstein
Feature cli: add `MarkdownRenderer.classdef_with_decorators` and `MarkdownRenderer.signature_with_decorators` options@NiklasRosenstein
Feature Add new `HugoRenderer` (YAML type name `hugo`).106@NiklasRosenstein
Feature smart-processor: now looks for a `@doc:fmt:` string in the docstring, which can be used to override the style that is used in case the automatically detected style is incorrect@NiklasRosenstein
Docs The Pydoc-Markdown documentation is now available on Read the Docs (
Feature api: Add new `Builder` interface that is used with the new `--build` and `--site-dir` options@NiklasRosenstein
Feature mkdocs: Implement `Builder` interface for `MkDocsRenderer`@NiklasRosenstein
Feature hugo: Implement `Builder` interface for `HugoRenderer`@NiklasRosenstein
Feature cli: Add new `--build` and `--site-dir` options as well as `--bootstrap readthedocs`@NiklasRosenstein
Fix mkdocs: Fix error in MkDocs navigation generation if a page has no `source` and no `contents`@NiklasRosenstein
Improvement mkdocs: generated `mkdocs.yml` now uses forward slashes for filenames on Windows system to increase portability129@NiklasRosenstein
Feature add new `$.hooks.pre-render` and `$` options112@NiklasRosenstein

3.1.1 (2020-06-26)

Improvement dependencies: bump dependency on `nr.databind.core` to `~0.0.18` to avoid picking up the bad `0.0.17` version126@NiklasRosenstein

3.1.0 (2020-06-04)

Improvement cli: rename `--watch-and-serve` option to `--server`@NiklasRosenstein
Improvement cli: watch and serve mainloop now reloads the config file and does not open the browser another time if it was already opened once.@NiklasRosenstein
Fix cli: fix `pydoc-markdown.yml` generated with `--bootstrap`118@NiklasRosenstein
Improvement markdown: * change default for `header_level_by_type` (`2` to `1` for modules, `3` to `2` for classes). * change default for `descriptive_class_title` (`false` to `true`) @NiklasRosenstein
Feature markdown: added `content_directory` option (replaces hardcoded default `docs` value, defaults to `content` now)@NiklasRosenstein
Improvement markdown: renamed `clean_docs_directory_on_render` to `clean_render` and change the default from `true` to `false`.@NiklasRosenstein
Improvement mkdocs: `mkdocs_config` option can now be set to `null` (the renderer will the refrain from writing a `mkdocs.yml` file into the output directory). @NiklasRosenstein
Fix python: fix assignments with annotations being ignored by the parser115@NiklasRosenstein

3.0.2 (2020-05-16)

Fix mkdocs: fix `NameError` in `MkdocsRenderer`@NiklasRosenstein

3.0.1 (2020-05-16)

Feature cli: added `--version` option@NiklasRosenstein
Feature cli: added `-p,--package` option (which overrides `PythonLoader.packages`)@NiklasRosenstein
Feature utils: added `` module@NiklasRosenstein
Feature cli: added `RenderSession` class to `pydoc_markdown.main` module which makes the cli logic easier to maintain and re-use.@NiklasRosenstein
Feature markdown: added hidden `MarkdownRenderer.fp` option@NiklasRosenstein
Feature python: added `PythonLoader.packages` option@NiklasRosenstein
Improvement python: changed behavior of `PythonLoader.modules` option (it will not only load the module that was explicitly specified and exclude any sub-modules, if applicable).@NiklasRosenstein
Improvement cli: dynamically lookup `MarkdownRenderer` configuration from the renderer to support renderers other than `MarkdownRenderer` and `MkdocsRenderer` that supply a `markdown` field that is an instance of `MarkdownRenderer` (so they can be used with `--render-toc` as well).@NiklasRosenstein

3.0.0 (2020-05-12)

Feature Initial release of Pydoc-Markdown v3.@NiklasRosenstein