Repolode
Submit
adamchainz

adamchainz/blacken-docs

A command-line tool that runs Black on Python code blocks inside Markdown, reStructuredText, and LaTeX documentation files.

View on GitHub
Stars
680
Forks
46
Open issues
18
Last commit
3 days ago

What is it?

blacken-docs rewrites Python code examples embedded in documentation so they follow the same formatting as the rest of a project's code. It handles python and pycon blocks in Markdown and reStructuredText, minted and PythonTeX blocks in LaTeX, and Markdown or reST inside Python docstrings.

It runs in place on the files you pass it and exits non-zero when a file changes, which makes it easy to use in CI or as a pre-commit hook. Black options such as line length, target version, and skip-string-normalization are passed through, and a --check mode reports needed changes without modifying files.

Formatting can be disabled for a specific block with blacken-docs:off and blacken-docs:on comments. Because Black changes over time, the project recommends pinning the Black version in the pre-commit configuration.

Key features

  • 01Formats python and pycon blocks in Markdown and reStructuredText files
  • 02Handles minted and PythonTeX code blocks in LaTeX documents
  • 03Reformats Markdown and reST code examples inside Python docstrings
  • 04Provides --check mode and exits non-zero when files change
  • 05Ships as a pre-commit hook with pinned Black versions

Use cases

  • Keeping Python snippets in a project's README or Markdown docs consistently formatted
  • Enforcing formatting of code examples in Sphinx-based reStructuredText documentation
  • Running documentation formatting checks in CI or pre-commit before merging changes

Quick start

  1. 1

    Install blacken-docs with pip

    python -m pip install blacken-docs
  2. 2

    Run blacken-docs on your documentation files

    blacken-docs README.rst

Things to know

  • Only formats Python code blocks inside Markdown, reStructuredText, and LaTeX files.
  • Does not recurse through directories; you must pass filenames or use globbing or pre-commit.

In collections

Static site generators & documentation tools

Topics

#python#black#documentation#code-formatting#pre-commit#markdown#restructuredtext#latex#docs

FAQ

What is blacken-docs?
A command-line tool that runs Black on Python code blocks inside Markdown, reStructuredText, and LaTeX documentation files. blacken-docs rewrites Python code examples embedded in documentation so they follow the same formatting as the rest of a project's code. It handles python and pycon blocks in Markdown and reStructuredText, minted and PythonTeX blocks in LaTeX, and Markdown or reST inside Python docstrings.
Is blacken-docs free to use? What license does it have?
blacken-docs is open source under the MIT license. Check the license terms before using it in commercial products.
Is blacken-docs still maintained?
Actively maintained. The last commit to blacken-docs was on Nov 4, 2026.
What can I use blacken-docs for?
Keeping Python snippets in a project's README or Markdown docs consistently formatted Enforcing formatting of code examples in Sphinx-based reStructuredText documentation Running documentation formatting checks in CI or pre-commit before merging changes
How do I install blacken-docs?
Install blacken-docs with pip: python -m pip install blacken-docs Run blacken-docs on your documentation files: blacken-docs README.rst
Where can I get blacken-docs?
The source code and installation instructions are on GitHub: https://github.com/adamchainz/blacken-docs

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects