griffe2md: Output API docs to Markdown using Griffe

1.5.0 · active · verified Thu Apr 16

griffe2md is a Python library that generates API documentation in Markdown format. It leverages Griffe for parsing Python source code and uses Jinja templates to render the extracted API data into Markdown, similar to how mkdocstrings-python generates HTML but for Markdown output. It primarily provides a command-line interface for ease of use. The library is actively maintained, currently at version 1.5.0, with regular updates addressing features and bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'griffe' (or similar errors related to griffelib)
```
cause In `griffe2md` versions 1.3.4 and later, the underlying parsing library `griffe` was replaced by `griffelib`. Older environments or explicit dependency pinning might lead to `griffe` being sought.

fix Ensure `griffelib` is installed: `pip install griffelib`. It is recommended to upgrade `griffe2md` to the latest version to get the correct dependency automatically: `pip install --upgrade griffe2md`.
```
Generated Markdown output is not formatted or pretty-printed.
```
cause As of `griffe2md` version 1.4.0, automatic formatting with `mdformat` is no longer enabled by default. Prior versions might have applied formatting automatically.

fix If automatic formatting is desired, run an external formatter like `mdformat` on the output file after `griffe2md` has generated it: `griffe2md markdown my_package > docs.md && mdformat docs.md`.
```
Markdown tables in generated documentation appear broken or incorrectly rendered.
```
cause Earlier versions of `griffe2md` had bugs in handling Markdown table syntax, such as not properly escaping pipe characters or newlines within table cells.

fix Upgrade `griffe2md` to the latest version (`1.3.3` or newer) to include fixes for table rendering issues: `pip install --upgrade griffe2md`.

Warnings

breaking Changed core dependency from `griffe` to `griffelib`.
Fix: Ensure `griffelib` is installed. If `griffe2md` was installed in an environment with a pinned `griffe` dependency, consider upgrading `griffe2md` or manually installing `griffelib`. [cite: "Depend on griffelib instead of griffe ([5c9b7e0](https://github.com/mkdocstrings/griffe2md/commit/5c9b7e02cf4deb1f4aa317379f4a13d5a1492e96) by Timothée Mazzucotelli)."]
gotcha Markdown output is no longer formatted by default using `mdformat`.
Fix: If you relied on automatic Markdown formatting, you will need to run `mdformat` separately on the generated output, or check for new configuration options in `griffe2md` to re-enable formatting if available. Version 1.3.0 added a parameter to *prevent* formatting, indicating the shift in default behavior. [cite: "Don't format code with mdformat by defa"]
gotcha Older versions may produce malformed Markdown tables due to improper escaping of pipes or handling of newlines.
Fix: Upgrade `griffe2md` to version 1.3.3 or later to benefit from fixes for escaping pipes in table cells and replacing newlines with `<br>` tags in table descriptions. [cite: "Remove extra `}}` in Jinja template ([cb8aeaf](https://github.com/mkdocstrings/griffe2md/commit/cb8aeaf9d230c9b702f002a9bb5cb8e85dd9a83b) by Timothée Mazzucotelli). [Issue-24](https://github.com/mkdocstrings/griffe2md/issues/24)", "Escape pipes in table cells ([0e1da47](https://github.com/mkdocstrings/griffe2md/commit/0e1da47) by Timothée Mazzucotelli).", "Replace newlines with `<br>` tags in table descriptions ([afd7ef0](https://github.com/mkdocstrings/griffe2md/commit/afd7ef0856c317064281d5ab3490e4d0ea437142) by Timothée Mazzucotelli). [Issue-16](https://github.com/mkdocstrings/griffe2md/issues/16)"]

Install

pip install griffe2md Pip
uv tool install griffe2md uv

Quickstart

To generate Markdown API documentation for a Python package, simply run the `griffe2md` command with the path to your source package. Use the `-o` or `--output` option to save the output to a file instead of standard output.

griffe2md markdown path/to/my/src/package -o api_docs.md

view raw JSON →