diff --git a/.mdformat.toml b/.mdformat.toml
new file mode 100644
index 00000000..2ba04a25
--- /dev/null
+++ b/.mdformat.toml
@@ -0,0 +1,2 @@
+[plugin.mkdocs]
+align_semantic_breaks_in_lists = true
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f0242a4e..a7d8c5b8 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -45,6 +45,14 @@ repos:
         exclude: ^docs/
         types_or: [javascript, jsx, ts, tsx, yaml, json, toml, html, css, scss, sass, markdown]
 
+      # mdformat for docs
+      - id: mdformat
+        name: mdformat
+        entry: mdformat
+        language: system
+        types_or: [markdown]
+        files: ^docs/
+
       # golangci-lint for Go code quality
       - id: golangci-lint
         name: golangci-lint
diff --git a/.prettierignore b/.prettierignore
index ebb727cc..9d8aa3bc 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -1,5 +1,2 @@
 .github/workflows/test-integration-v2*
-docs/about/features.md
-docs/ref/api.md
-docs/ref/configuration.md
-docs/ref/oidc.md
+docs/
diff --git a/Makefile b/Makefile
index 1e08cda9..0bb63e4f 100644
--- a/Makefile
+++ b/Makefile
@@ -21,7 +21,7 @@ endef
 # Source file collections using shell find for better performance
 GO_SOURCES := $(shell find . -name '*.go' -not -path './gen/*' -not -path './vendor/*')
 PROTO_SOURCES := $(shell find . -name '*.proto' -not -path './gen/*' -not -path './vendor/*')
-DOC_SOURCES := $(shell find . \( -name '*.md' -o -name '*.yaml' -o -name '*.yml' -o -name '*.ts' -o -name '*.js' -o -name '*.html' -o -name '*.css' -o -name '*.scss' -o -name '*.sass' \) -not -path './gen/*' -not -path './vendor/*' -not -path './node_modules/*')
+PRETTIER_SOURCES := $(shell find . \( -name '*.md' -o -name '*.yaml' -o -name '*.yml' -o -name '*.ts' -o -name '*.js' -o -name '*.html' -o -name '*.css' -o -name '*.scss' -o -name '*.sass' \) -not -path './gen/*' -not -path './vendor/*' -not -path './node_modules/*')
 
 # Default target
 .PHONY: all
@@ -33,6 +33,7 @@ check-deps:
 	$(call check_tool,go)
 	$(call check_tool,golangci-lint)
 	$(call check_tool,gofumpt)
+	$(call check_tool,mdformat)
 	$(call check_tool,prettier)
 	$(call check_tool,clang-format)
 	$(call check_tool,buf)
@@ -52,7 +53,7 @@ test: check-deps $(GO_SOURCES) go.mod go.sum
 
 # Formatting targets
 .PHONY: fmt
-fmt: fmt-go fmt-prettier fmt-proto
+fmt: fmt-go fmt-mdformat fmt-prettier fmt-proto
 
 .PHONY: fmt-go
 fmt-go: check-deps $(GO_SOURCES)
@@ -60,9 +61,14 @@ fmt-go: check-deps $(GO_SOURCES)
 	gofumpt -l -w .
 	golangci-lint run --fix
 
+.PHONY: fmt-mdformat
+fmt-mdformat: check-deps
+	@echo "Formatting documentation..."
+	mdformat docs/
+
 .PHONY: fmt-prettier
-fmt-prettier: check-deps $(DOC_SOURCES)
-	@echo "Formatting documentation and config files..."
+fmt-prettier: check-deps $(PRETTIER_SOURCES)
+	@echo "Formatting markup and config files..."
 	prettier --write '**/*.{ts,js,md,yaml,yml,sass,css,scss,html}'
 
 .PHONY: fmt-proto
@@ -116,7 +122,8 @@ help:
 	@echo ""
 	@echo "Specific targets:"
 	@echo "  fmt-go       - Format Go code only"
-	@echo "  fmt-prettier - Format documentation only"
+	@echo "  fmt-mdformat - Format documentation only"
+	@echo "  fmt-prettier - Format markup and config files only"
 	@echo "  fmt-proto    - Format Protocol Buffer files only"
 	@echo "  lint-go      - Lint Go code only"
 	@echo "  lint-proto   - Lint Protocol Buffer files only"
diff --git a/README.md b/README.md
index 12f5d791..4814c210 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,8 @@ run `make lint` and `make fmt` before committing any code.
 The **Proto** code is linted with [`buf`](https://docs.buf.build/lint/overview) and
 formatted with [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html).
 
+The **docs** are formatted with [`mdformat`](https://mdformat.readthedocs.io).
+
 The **rest** (Markdown, YAML, etc) is formatted with [`prettier`](https://prettier.io).
 
 Check out the `.golangci.yaml` and `Makefile` to see the specific configuration.
diff --git a/flake.nix b/flake.nix
index ae02d0ff..4649f31b 100644
--- a/flake.nix
+++ b/flake.nix
@@ -179,6 +179,10 @@
             yq-go
             ripgrep
             postgresql
+            python313Packages.mdformat
+            python313Packages.mdformat-footnote
+            python313Packages.mdformat-frontmatter
+            python313Packages.mdformat-mkdocs
             prek
 
             # 'dot' is needed for pprof graphs