blacken-docs
Run Black on Python code blocks in documentation files.
Decision gist · record as of 2026-08-14
Yes. This is a lightweight, actively maintained tool with no security vulnerabilities and a single stable dependency. Install it if you maintain documentation with embedded Python code and want to keep those examples formatted consistently with Black. The pre-commit integration makes it a natural fit for projects already using Black.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires black 22.1.0 or later; best practice is to pin black version in pre-commit additional_dependencies to avoid format drift.
- Low friction: single runtime dependency on black, pure Python wheel, actively maintained with recent releases.
- Supports Python 3.9 to 3.14.
License · maintenance · safety
MIT (permissive) — MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for any project type.
last release 2025-09-08 (340 days) · last repo commit 2026-08-14 · 680 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 131,001 downloads/mo, #11,614 on PyPI
Alternatives
Verify before relying
pip install blacken-docs
blacken-docs README.rst
# Or in a pre-commit hook:
# Add to .pre-commit-config.yaml:
# - repo: https://github.com/adamchainz/blacken-docs
# rev: "1.20.0"
# hooks:
# - id: blacken-docs
# additional_dependencies:
# - black==22.12.0- Whether the tool correctly handles edge cases in mixed-format documentation (e.g., nested code blocks or unusual indentation).
- Performance characteristics when processing large documentation sets or files with many code blocks.
What it is and what it does
blacken-docs is a command-line tool that runs Black's code formatter on Python code blocks found within documentation files. It recognizes Python code in Markdown fenced blocks (```python and ```pycon), reStructuredText code-block directives, LaTeX minted and pycode environments, and Python docstrings. The tool rewrites files in place and exits with a non-zero status if any changes were made, making it suitable for CI/CD pipelines and pre-commit hooks.
The package depends solely on black and is designed to keep documentation examples in sync with your project's code style. It supports Black's key options (line length, target version, string normalization, preview mode) and adds its own flags for dry-run checking, error suppression, and optional reStructuredText literal-block formatting. It does not recurse directories—you provide explicit file paths or use shell globbing and pre-commit integration to apply it across many files.
Use it for
- Enforce consistent code style in README and API documentation examples alongside your main codebase formatting.
- Integrate into pre-commit hooks to automatically reformat code blocks in pull requests before commit.
- Verify documentation code blocks are syntactically valid and properly formatted as part of CI checks.
- Reformat Python code examples embedded in docstrings when refactoring or upgrading Black versions.
- Maintain LaTeX documentation with minted code blocks in a consistent style with your project's Black config.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes.
This is a lightweight, actively maintained tool with no security vulnerabilities and a single stable dependency. Install it if you maintain documentation with embedded Python code and want to keep those examples formatted consistently with Black. The pre-commit integration makes it a natural fit for projects already using Black.
Install
blacken-docs on PyPI
Before you install
Low friction: single runtime dependency on black, pure Python wheel, actively maintained with recent releases. Supports Python 3.9 to 3.14.
Requires black 22.1.0 or later; best practice is to pin black version in pre-commit additional_dependencies to avoid format drift.
License in practice
MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for any project type.
Quickstart
pip install blacken-docs
blacken-docs README.rst
# Or in a pre-commit hook:
# Add to .pre-commit-config.yaml:
# - repo: https://github.com/adamchainz/blacken-docs
# rev: "1.20.0"
# hooks:
# - id: blacken-docs
# additional_dependencies:
# - black==22.12.0Verify before relying
- Whether the tool correctly handles edge cases in mixed-format documentation (e.g., nested code blocks or unusual indentation).
- Performance characteristics when processing large documentation sets or files with many code blocks.
Package facts
| License | MIT permissive |
| Python support | Supports the current Python release >=3.9 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 1 packageblack |
| Maintenance | Actively maintained 340 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 131,001 / month, #11,614 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableIntended Audience :: DevelopersNatural Language :: EnglishOperating System :: OS IndependentProgramming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Programming Language :: Python :: 3.9Typing :: Typed |
Evidence: blacken_docs-1.20.0-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “black code formatter documentation”
- blacken-docsApplies Black code formatting to Python code blocks embedded in…
- mdformat-blackA plugin for mdformat that automatically formats Python code blocks…
- docstrfmtAutomatically formats reStructuredText in files and Python docstrings…
Give your agent the search over MCP, or paste the wish link into any chat.
More Documentation packages
Docutils converts plaintext documentation in reStructuredText format into multiple output formats including HTML, XML, and LaTeX using a modular processing system.
Sphinx generates professional documentation from reStructuredText source files, producing HTML, PDF, EPUB, and other formats with automatic cross-references, code highlighting, and hierarchical navigation.
Griffe extracts the complete structure and signatures of Python programs to generate API documentation or detect breaking changes in your project's public API.
Install it if you need to programmatically inspect Python code structure, generate API docs, or enforce API stability in CI.
A Sphinx extension that outputs documentation in serialized HTML formats (JSON and pickle) alongside standard HTML.
Alabaster is a clean, responsive Sphinx theme for documentation that requires Python 3.10 or newer and Sphinx 6.2 or newer.
A Sphinx extension that generates HTML help files from reStructuredText documentation source.
See also darker · doccmd · black · docstrfmt · mdformat-ruff · mdformat-black · reformat-gherkin · nbqa · flake8-black · markdown-exec