{"id":7988,"library":"blacken-docs","title":"blacken-docs","description":"blacken-docs is a command-line tool that formats Python code blocks within various documentation files (Markdown, reStructuredText, LaTeX, and Python docstrings) using the opinionated `Black` formatter. It operates by rewriting files in place. The library is currently at version 1.20.0, actively maintained, and releases occur periodically to support new Python versions and `Black` features.","status":"active","version":"1.20.0","language":"en","source_language":"en","source_url":"https://github.com/asottile/blacken-docs","tags":["formatting","code quality","documentation","black","pre-commit"],"install":[{"cmd":"pip install blacken-docs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core formatter used for code blocks. It is highly recommended to pin its version when using blacken-docs as a pre-commit hook due to Black's evolving style.","package":"black"}],"imports":[],"quickstart":{"code":"pip install blacken-docs\n\n# Format a specific Markdown file\nblacken-docs README.md\n\n# Format all reStructuredText files in the current directory\nblacken-docs *.rst\n\n# Example .pre-commit-config.yaml entry (recommended):\n# See https://github.com/adamchainz/blacken-docs for latest revision\n# - repo: https://github.com/asottile/blacken-docs\n#   rev: v1.20.0 # Use the latest stable tag\n#   hooks:\n#     - id: blacken-docs\n#       additional_dependencies: ['black==24.4.0'] # Pin Black version!","lang":"bash","description":"Install `blacken-docs` and run it from the command line on individual files or using glob patterns. The most common and recommended usage is as a `pre-commit` hook to automate formatting documentation code blocks."},"warnings":[{"fix":"When using `blacken-docs` as a `pre-commit` hook, always specify the `black` version in `additional_dependencies` (e.g., `additional_dependencies: ['black==24.4.0']`) in your `.pre-commit-config.yaml` to ensure consistent formatting.","message":"`Black`'s formatting style evolves. If not explicitly pinned, `blacken-docs` (especially in `pre-commit` hooks) may use different `Black` versions, leading to inconsistent formatting or repeated changes.","severity":"breaking","affected_versions":"All versions"},{"fix":"This behavior is by design, indicating that files needed formatting. In CI/CD, this usually means the job failed and needs the formatted changes committed. Use the `--check` option to only check for changes without modifying files, returning a non-zero code if changes are needed. The `--skip-errors` (or `-E`) option can prevent non-zero exits for Black's internal syntax errors.","message":"`blacken-docs` exits with a non-zero status code (typically 1) if it modifies any files or encounters parsing errors from `Black`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If `Black` complains about `...` not being syntactically valid in a code block, replace it with `# ...` or ensure the code block is fully syntactically valid without needing an ellipsis.","message":"Using the ellipsis `...` to represent missing code in examples can sometimes cause `Black` to report syntax errors, even though `...` is valid Python.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the code within the block is valid Python syntax. If using `pycon` blocks with `>>>` prompts, ensure your `blacken-docs` version is 1.9.0 or newer, which added explicit support for these.","cause":"This error occurs when `blacken-docs` or `Black` cannot parse the content of a code block, typically due to invalid Python syntax, an incorrect language specifier, or malformed `pycon` (interactive console) blocks in older versions.","error":"code block parse error Cannot parse: X:Y: <error_details>"},{"fix":"Standardize the `Black` version across all environments. For `pre-commit`, explicitly pin `Black` in `additional_dependencies` of the `blacken-docs` hook (e.g., `additional_dependencies: ['black==24.4.0']`). Ensure your local `black` installation matches this version, or exclusively rely on `pre-commit` for formatting.","cause":"This 'formatting loop' usually indicates that different versions of `Black` are being used by your local environment, `pre-commit` hook, and/or CI system, leading to conflicting formatting styles.","error":"pre-commit hook 'blacken-docs' fails and reformats files, then subsequent local `black` runs or CI checks fail, creating a formatting loop."}]}