diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 5da5eb203726a..3008412e55a5a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -23,6 +23,7 @@ repos:
       - id: mdformat
         additional_dependencies:
           - mdformat-mkdocs
+          - mdformat-admon
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: v0.33.0
diff --git a/docs/configuration.md b/docs/configuration.md
index e963c310e6000..0e728313ee237 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -375,6 +375,70 @@ Running `ruff check --select F401` would result in Ruff enforcing `F401`, and no
 Running `ruff check --extend-select B` would result in Ruff enforcing the `E`, `F`, and `B` rules,
 with the exception of `F401`.
 
+## Fixes
+
+Ruff supports automatic fixes for a variety of lint errors. For example, Ruff can remove unused
+imports, reformat docstrings, rewrite type annotations to use newer Python syntax, and more.
+
+To enable fixes, pass the `--fix` flag to `ruff check`:
+
+```shell
+ruff check . --fix
+```
+
+By default, Ruff will fix all violations for which safe fixes are available; to determine
+whether a rule supports fixing, see [_Rules_](rules.md).
+
+### Fix safety
+
+Ruff labels fixes as "safe" and "unsafe". The meaning and intent of your code will be retained when applying safe fixes, but the meaning could be changed when applying unsafe fixes.
+
+Ruff only enables safe fixes by default. Unsafe fixes can be enabled by settings [`unsafe-fixes`](settings.md#unsafe-fixes) in your configuration file or passing the `--unsafe-fixes` flag to `ruff check`:
+
+```shell
+# Show unsafe fixes
+ruff check . --unsafe-fixes
+
+# Apply unsafe fixes
+ruff check . --fix --unsafe-fixes 
+```
+
+The safety of fixes can be adjusted per rule using the [`extend-safe-fixes`](settings.md#extend-safe-fixes) and [`extend-unsafe-fixes`](settings.md#extend-unsafe-fixes) settings.
+
+For example, the following configuration would promote unsafe fixes for `F601` to safe fixes and demote safe fixes for `UP034` to unsafe fixes:
+
+```toml
+[tool.ruff.lint]
+extend-safe-fixes = ["F601"]
+extend-unsafe-fixes = ["UP034"]
+```
+
+You may use prefixes to select rules as well, e.g., `F` can be used to promote fixes for all rules in Pyflakes to safe.
+
+!!! note
+    All fixes will always be displayed by Ruff when using the `json` output format. The safety of each fix is available under the `applicability` field.
+
+### Disabling fixes
+
+To limit the set of rules that Ruff should fix, use the [`fixable`](settings.md#fixable) and [`unfixable`](settings.md#unfixable) settings, along with their [`extend-fixable`](settings.md#extend-fixable) and [`extend-unfixable`](settings.md#extend-unfixable)
+variants.
+
+For example, the following configuration would enable fixes for all rules except
+[`unused-imports`](rules/unused-import.md) (`F401`):
+
+```toml
+[tool.ruff.lint]
+fixable = ["ALL"]
+unfixable = ["F401"]
+```
+
+Conversely, the following configuration would only enable fixes for `F401`:
+
+```toml
+[tool.ruff.lint]
+fixable = ["F401"]
+```
+
 ## Error suppression
 
 To omit a lint rule entirely, add it to the "ignore" list via [`ignore`](settings.md#ignore)
diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index 171578868d1a0..7eeed400e8e22 100644
--- a/mkdocs.template.yml
+++ b/mkdocs.template.yml
@@ -37,6 +37,8 @@ site_author: charliermarsh
 site_url: https://docs.astral.sh/ruff/
 site_dir: site/ruff
 markdown_extensions:
+  - admonition
+  - pymdownx.details
   - toc:
       permalink: "#"
   - pymdownx.snippets: