adamchainz/blacken-docs

这是什么？

核心功能

• 01格式化 Markdown 与 reStructuredText 文件中的 python 和 pycon 代码块
• 02处理 LaTeX 文档中的 minted 和 PythonTeX 代码块
• 03重新格式化 Python 文档字符串中的 Markdown 和 reST 代码示例
• 04提供 --check 模式，文件有改动时以非零状态码退出
• 05可作为 pre-commit 钩子使用，并支持固定 Black 版本

适用场景

• 保持项目 README 或 Markdown 文档中的 Python 代码片段格式统一
• 统一基于 Sphinx 的 reStructuredText 文档中的代码示例格式
• 在 CI 或 pre-commit 中检查文档代码格式，合并前自动拦截问题

快速上手

1. 1

   使用 pip 安装 blacken-docs

   python -m pip install blacken-docs
2. 2

   对文档文件运行 blacken-docs

   blacken-docs README.rst

使用前须知

• !仅格式化 Markdown、reStructuredText 和 LaTeX 文件中的 Python 代码块。
• !不会递归遍历目录，需要传入文件名或使用通配符或 pre-commit。

收录于专题

标签

常见问题

blacken-docs 是什么？

一个命令行工具，用 Black 格式化 Markdown、reStructuredText 和 LaTeX 文档中的 Python 代码块。 blacken-docs 会重写文档中嵌入的 Python 示例代码，使其与项目其他代码保持相同的格式。它支持 Markdown 和 reStructuredText 中的 python、pycon 代码块，LaTeX 中的 minted 与 PythonTeX 代码块，以及 Python 文档字符串中的 Markdown 或 reST 代码块。

blacken-docs 可以免费使用吗？用的什么许可证？

blacken-docs 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。

blacken-docs 还在维护吗？

活跃维护中。blacken-docs 最近一次提交是在 2026年11月4日。

blacken-docs 适合用来做什么？

保持项目 README 或 Markdown 文档中的 Python 代码片段格式统一 统一基于 Sphinx 的 reStructuredText 文档中的代码示例格式 在 CI 或 pre-commit 中检查文档代码格式，合并前自动拦截问题

blacken-docs 怎么安装和运行？

使用 pip 安装 blacken-docs: python -m pip install blacken-docs 对文档文件运行 blacken-docs: blacken-docs README.rst

在哪里获取 blacken-docs？

源代码和安装说明在 GitHub 上：https://github.com/adamchainz/blacken-docs