{"id":13492593,"url":"https://github.com/adamchainz/blacken-docs","last_synced_at":"2026-03-08T16:31:27.800Z","repository":{"id":32514198,"uuid":"135868210","full_name":"adamchainz/blacken-docs","owner":"adamchainz","description":"Run `black` on python code blocks in documentation files","archived":false,"fork":false,"pushed_at":"2024-04-29T21:02:38.000Z","size":404,"stargazers_count":611,"open_issues_count":14,"forks_count":41,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-05-01T12:52:52.074Z","etag":null,"topics":["black","docs","pre-commit"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adamchainz.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-03T02:48:01.000Z","updated_at":"2024-05-03T20:52:25.292Z","dependencies_parsed_at":"2023-10-14T06:33:46.260Z","dependency_job_id":"57504ea3-105a-49a0-a122-55d02a91d4b7","html_url":"https://github.com/adamchainz/blacken-docs","commit_stats":null,"previous_names":["asottile/blacken-docs"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamchainz%2Fblacken-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamchainz%2Fblacken-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamchainz%2Fblacken-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamchainz%2Fblacken-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adamchainz","download_url":"https://codeload.github.com/adamchainz/blacken-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222369834,"owners_count":16973287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["black","docs","pre-commit"],"created_at":"2024-07-31T19:01:07.343Z","updated_at":"2025-12-29T22:33:39.606Z","avatar_url":"https://github.com/adamchainz.png","language":"Python","funding_links":[],"categories":["Python","Documentation"],"sub_categories":[],"readme":"============\nblacken-docs\n============\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/blacken-docs/main.yml.svg?branch=main\u0026style=for-the-badge\n   :target: https://github.com/adamchainz/blacken-docs/actions?workflow=CI\n\n.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge\n  :target: https://github.com/adamchainz/blacken-docs/actions?workflow=CI\n\n.. image:: https://img.shields.io/pypi/v/blacken-docs.svg?style=for-the-badge\n   :target: https://pypi.org/project/blacken-docs/\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\n   :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white\u0026style=for-the-badge\n   :target: https://github.com/pre-commit/pre-commit\n   :alt: pre-commit\n\nRun `Black \u003chttps://pypi.org/project/black/\u003e`__ on Python code blocks in documentation files.\n\nInstallation\n============\n\nUse **pip**:\n\n.. code-block:: sh\n\n    python -m pip install blacken-docs\n\nPython 3.10 to 3.14 supported.\n\nBlack 22.1.0+ supported.\n\npre-commit hook\n---------------\n\nYou can also install blacken-docs as a `pre-commit \u003chttps://pre-commit.com/\u003e`__ hook.\nAdd the following to the ``repos`` section of your ``.pre-commit-config.yaml`` file (`docs \u003chttps://pre-commit.com/#plugins\u003e`__):\n\n.. code-block:: yaml\n\n    -   repo: https://github.com/adamchainz/blacken-docs\n        rev: \"\"  # replace with latest tag on GitHub\n        hooks:\n        -   id: blacken-docs\n            additional_dependencies:\n            - black==22.12.0\n\nThen, reformat your entire project:\n\n.. code-block:: sh\n\n    pre-commit run blacken-docs --all-files\n\nSince Black is a moving target, it’s best to pin it in ``additional_dependencies``, and upgrade as appropriate.\nIf you have Black installed as another hook, you can automate upgrading this pinned hook using `sync-pre-commit-deps \u003chttps://github.com/pre-commit/sync-pre-commit-deps\u003e`__.\n\nUsage\n=====\n\nblacken-docs is a command line tool that rewrites documentation files in place.\nIt supports Markdown, reStructuredText, and LaTex files.\nAdditionally, you can run it on Python files to reformat Markdown and reStructuredText within docstrings.\n\nRun ``blacken-docs`` with the filenames to rewrite:\n\n.. code-block:: sh\n\n    blacken-docs README.rst\n\nIf any file is modified, ``blacken-docs`` exits nonzero.\n\n``blacken-docs`` does not have any ability to recurse through directories.\nUse the pre-commit integration, globbing, or another technique for applying to many files.\nFor example, |with git ls-files pipe xargs|_:\n\n.. |with git ls-files pipe xargs| replace:: with ``git ls-files | xargs``\n.. _with git ls-files pipe xargs: https://adamj.eu/tech/2022/03/09/how-to-run-a-command-on-many-files-in-your-git-repository/\n\n.. code-block:: sh\n\n    git ls-files -z -- '*.md' | xargs -0 blacken-docs\n\n…or PowerShell’s |ForEach-Object|__:\n\n.. |ForEach-Object| replace:: ``ForEach-Object``\n__ https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/foreach-object\n\n.. code-block:: powershell\n\n    git ls-files -- '*.md' | %{blacken-docs $_}\n\nblacken-docs currently passes the following options through to Black:\n\n* |-l / --line-length|__\n\n  .. |-l / --line-length| replace:: ``-l`` / ``--line-length``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#l-line-length\n\n* |--preview|__\n\n  .. |--preview| replace:: ``--preview``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#preview\n\n* |--pyi|__\n\n  .. |--pyi| replace:: ``--pyi``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#pyi\n\n* |-S / --skip-string-normalization|__\n\n  .. |-S / --skip-string-normalization| replace:: ``-S`` / ``--skip-string-normalization``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#s-skip-string-normalization\n\n* |-t / --target-version|__\n\n  .. |-t / --target-version| replace:: ``-t`` / ``--target-version``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#t-target-version\n\nIt also has the below extra options:\n\n* ``--check`` - Don’t modify files but indicate when changes are necessary with a message and non-zero return code.\n* ``-E`` / ``--skip-errors`` - Don’t exit non-zero for errors from Black (normally syntax errors).\n* ``--rst-literal-blocks`` - Also format literal blocks in reStructuredText files (more below).\n\nHistory\n=======\n\nblacken-docs was created by `Anthony Sottile \u003chttps://github.com/asottile/\u003e`__ in 2018.\nAt the end of 2022, Adam Johnson took over maintenance.\n\nSupported code block formats\n============================\n\nblacken-docs formats code blocks matching the following patterns.\n\nMarkdown\n--------\n\nIn “python” blocks:\n\n.. code-block:: markdown\n\n    ```python\n    def hello():\n        print(\"hello world\")\n    ```\n\nAnd “pycon” blocks:\n\n.. code-block:: markdown\n\n    ```pycon\n\n    \u003e\u003e\u003e def hello():\n    ...     print(\"hello world\")\n    ...\n\n    ```\n\nPrevent formatting within a block using ``blacken-docs:off`` and ``blacken-docs:on`` comments:\n\n.. code-block:: markdown\n\n    \u003c!-- blacken-docs:off --\u003e\n    ```python\n    # whatever you want\n    ```\n    \u003c!-- blacken-docs:on --\u003e\n\nWithin Python files, docstrings that contain Markdown code blocks may be reformatted:\n\n.. code-block:: python\n\n    def f():\n        \"\"\"docstring here\n\n        ```python\n        print(\"hello world\")\n        ```\n        \"\"\"\n\nreStructuredText\n----------------\n\nIn “python” blocks:\n\n.. code-block:: rst\n\n    .. code-block:: python\n\n        def hello():\n            print(\"hello world\")\n\nIn “pycon” blocks:\n\n.. code-block:: rst\n\n    .. code-block:: pycon\n\n        \u003e\u003e\u003e def hello():\n        ...     print(\"hello world\")\n        ...\n\nPrevent formatting within a block using ``blacken-docs:off`` and ``blacken-docs:on`` comments:\n\n.. code-block:: rst\n\n    .. blacken-docs:off\n\n    .. code-block:: python\n\n        # whatever you want\n\n    .. blacken-docs:on\n\nUse ``--rst-literal-blocks`` to also format `literal blocks \u003chttps://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks\u003e`__:\n\n.. code-block:: rst\n\n    An example::\n\n        def hello():\n            print(\"hello world\")\n\nLiteral blocks are marked with ``::`` and can be any monospaced text by default.\nHowever Sphinx interprets them as Python code `by default \u003chttps://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks\u003e`__.\nIf your project uses Sphinx and such a configuration, add ``--rst-literal-blocks`` to also format such blocks.\n\nWithin Python files, docstrings that contain reStructuredText code blocks may be reformatted:\n\n.. code-block:: python\n\n    def f():\n        \"\"\"docstring here\n\n        .. code-block:: python\n\n            print(\"hello world\")\n        \"\"\"\n\nLaTeX\n-----\n\nIn minted “python” blocks:\n\n.. code-block:: latex\n\n    \\begin{minted}{python}\n    def hello():\n        print(\"hello world\")\n    \\end{minted}\n\nIn minted “pycon” blocks:\n\n.. code-block:: latex\n\n    \\begin{minted}{pycon}\n    \u003e\u003e\u003e def hello():\n    ...     print(\"hello world\")\n    ...\n    \\end{minted}\n\nIn PythonTeX blocks:\n\n.. code-block:: latex\n\n    \\begin{pycode}\n    def hello():\n        print(\"hello world\")\n    \\end{pycode}\n\nPrevent formatting within a block using ``blacken-docs:off`` and ``blacken-docs:on`` comments:\n\n.. code-block:: latex\n\n    % blacken-docs:off\n    \\begin{minted}{python}\n    # whatever you want\n    \\end{minted}\n    % blacken-docs:on\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamchainz%2Fblacken-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadamchainz%2Fblacken-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamchainz%2Fblacken-docs/lists"}