diff --git a/README.md b/README.md
index 64c4ddb..dff2483 100644
--- a/README.md
+++ b/README.md
@@ -45,7 +45,7 @@ Sensible defaults for all included tools are provided.
   - Performance benchmarking with [pytest-benchmark](https://pytest-benchmark.readthedocs.io/)
   - Additional pytest plugins for a better testing experience
 - Code formatting with [Black](https://black.readthedocs.io/) or [Ruff formatter](https://docs.astral.sh/ruff/formatter/)
-- Documentation formatting with [blacken-docs](https://github.com/adamchainz/blacken-docs/)
+- Documentation formatting with [blacken-docs](https://github.com/adamchainz/blacken-docs/) (Black) or [Ruff formatter](https://docs.astral.sh/ruff/formatter/#markdown-code-formatting) (Ruff)
 - Comprehensive linting with [Ruff](https://docs.astral.sh/ruff/)
   - Replaces Flake8, isort, pyupgrade, yesqa, pycln, and dozens of plugins
 - Static type checking with [MyPy](https://mypy-lang.org/)
diff --git a/ctt.toml b/ctt.toml
index c763e74..09f1f48 100644
--- a/ctt.toml
+++ b/ctt.toml
@@ -24,12 +24,13 @@ _post_tasks = [
     --from git+https://github.com/scientific-python/cookie \
     --with repo-review[cli] \
     sp-repo-review . \
-    --ignore PY007,RTD,PC191 \
+    --ignore PY007,RTD,PC111,PC191 \
     --show errskip\
   """,
   # PY007 : Supports an easy task runner (nox, tox, pixi, etc.) : we use just
   "[ -f justfile ]",
   # RTD : ReadTheDocs : checked in the docs section
+  # PC111 : Uses blacken-docs : only used in the black variant; ruff format handles md code blocks
   # PC191 : Ruff show fixes if fixes enabled : false-positive on ruff-isort
 
   # show outdated deps
diff --git a/project_name/.pre-commit-config.yaml.jinja b/project_name/.pre-commit-config.yaml.jinja
index 2c42bd4..592739d 100644
--- a/project_name/.pre-commit-config.yaml.jinja
+++ b/project_name/.pre-commit-config.yaml.jinja
@@ -141,22 +141,17 @@ repos:
       - id: doc8
 
   # Python files
+  {%- if format_tool == "black" %}
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: <placeholder_until_update_deps>
     hooks:
-      {%- if format_tool == "black" %}
       - id: black{% if contains_jupyter_files %}-jupyter{% endif %}
-      {%- endif %}
-      {%- if format_tool != "black" or contains_jupyter_files %}
-      # used to keep the blacken-docs in sync
-      - id: black
-        stages: [manual]
-      {%- endif %}
   - repo: https://github.com/adamchainz/blacken-docs
     rev: <placeholder_until_update_deps>
     hooks:
       - id: blacken-docs
         additional_dependencies: [black==<placeholder_until_update_deps>]
+  {%- endif %}
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: <placeholder_until_update_deps>
     hooks:
@@ -166,6 +161,7 @@ repos:
         args: [--select, I001, --fix]
       {%- if format_tool == "ruff" %}
       - id: ruff-format
+        types_or: [python, pyi, jupyter, markdown]
       {%- endif %}
       - id: ruff-check
   - repo: https://github.com/pre-commit/mirrors-mypy
diff --git a/project_name/CONTRIBUTING.md.jinja b/project_name/CONTRIBUTING.md.jinja
index a658f82..2d0ad75 100644
--- a/project_name/CONTRIBUTING.md.jinja
+++ b/project_name/CONTRIBUTING.md.jinja
@@ -58,7 +58,7 @@ Ready to get started? Follow the development setup below.
 You can run specific tools directly:
 
 ```bash
-{% if format_tool == "black" %}uv run black{% endif %}
+{% if format_tool == "black" %}uv run black{% elif format_tool == "ruff" %}uv run ruff format{% endif %}
 uv run ruff check
 uv run mypy
 uv run pytest
diff --git a/project_name/justfile.jinja b/project_name/justfile.jinja
index e4a183d..a893b8f 100644
--- a/project_name/justfile.jinja
+++ b/project_name/justfile.jinja
@@ -39,7 +39,9 @@ deps-update: && deps-list-outdated
   uv sync --upgrade
   uv run prek auto-update
   uvx sync-with-uv
+  {%- if format_tool == "black" %}
   just _sync-blacken-docs
+  {%- endif %}
   uvx sync-pre-commit-deps --yaml-mapping 2 --yaml-sequence 4 --yaml-offset 2 .pre-commit-config.yaml || { \
     echo "Note: '.pre-commit-config.yaml' changed, and might lost its formatting." \
     && exit 1; \
@@ -48,13 +50,14 @@ deps-update: && deps-list-outdated
 # Audit dependencies
 deps-audit:
   uv audit --locked
-
+{% if format_tool == "black" %}
 # Sync blacken-docs' black additional_dependency with the version in uv.lock
 _sync-blacken-docs:
   @black_ver=$(awk -F'"' '/^\[\[package\]\]/{p=0} /^name = "black"$/{p=1} p && /^version =/{print $2; exit}' uv.lock); \
     if [ -n "$black_ver" ] && grep -q 'id: blacken-docs' .pre-commit-config.yaml; then \
       sed -i -E "/id: blacken-docs/,/^  - repo:/ s/(black==)(<[^>]*>|[0-9][0-9a-z.+-]*)/\1$black_ver/" .pre-commit-config.yaml; \
     fi
+{%- endif %}
 
 
 ### code quality ###
@@ -84,10 +87,10 @@ format:
   uv run ruff check --select I001 --fix
   {%- if format_tool == "black" %}
   uv run black .
+  uv run prek run --all-files blacken-docs
   {%- elif format_tool == "ruff" %}
   uv run ruff format
   {%- endif %}
-  uv run prek run --all-files blacken-docs
   uv run prek run --all-files mdformat
   {%- if jupyter_files == "strip_outputs" %}
   uv run prek run --all-files nbstripout
diff --git a/project_name/pyproject.toml.jinja b/project_name/pyproject.toml.jinja
index 28932e6..538c976 100644
--- a/project_name/pyproject.toml.jinja
+++ b/project_name/pyproject.toml.jinja
@@ -72,7 +72,9 @@ dev = [
   ## used in the justfile
   "rust-just ~=1.0",
   "prek ~=0.4.0",
+  {%- if format_tool == "black" %}
   "black{% if contains_jupyter_files %}[jupyter]{% endif %} ~=26.1",
+  {%- endif %}
   "ruff ~=0.15.0",
   ## can be used for debug
   "icecream >=2",
@@ -216,9 +218,18 @@ enable_error_code = [
 DEP002 = [
 ]
 
+{% if format_tool == "ruff" %}
+[tool.ruff]
+# discover Markdown files so `ruff format` can format their code blocks
+extend-include = ["*.md"]
 
+{% endif %}
 [tool.ruff.format]
 docstring-code-format = true
+{%- if format_tool == "ruff" %}
+# enable preview mode to format code blocks inside Markdown files
+preview = true
+{%- endif %}
 
 
 [tool.ruff.lint]