diff --git a/docs/mlir_interoperation.md b/docs/guides/mlir_interoperation.md
similarity index 93%
rename from docs/mlir_interoperation.md
rename to docs/guides/mlir_interoperation.md
index 323ef4c7e2..683862cc43 100644
--- a/docs/mlir_interoperation.md
+++ b/docs/guides/mlir_interoperation.md
@@ -1,6 +1,6 @@
 ## Generating executables through MLIR
 
-As mentioned previously, xDSL can interoperate with MLIR as its backend. As this
+xDSL can interoperate with MLIR as its backend. As this
 requires an installation, and therefore a compilation, of a lot of the LLVM
 project and MLIR, this functonality is not distributed with xDSL by default. To
 actually leverage from this functionality, first clone and build MLIR. Please
diff --git a/mkdocs.yml b/mkdocs.yml
index b2a6c1aed3..2a55bdeb86 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -2,14 +2,41 @@ site_name: xDSL
 
 theme:
   name: "material"
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
 
 plugins:
 - search
-- mkdocstrings
+- gen-files:
+    scripts:
+    - scripts/gen_ref_pages.py
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          docstring_style: google
+          members_order: source
+          show_root_heading: true
+          show_root_full_path: false
+          show_signature_annotations: true
 
-
-# nav:
-#   - xDSL: index.md
-#   - API Reference:
-#     - API Reference: api/index.md
-#     - Core IR Data Structures: api/ir/index.md
+nav:
+  - xDSL: index.md
+  - API Reference:
+    - API Reference: api/index.md
+    - Core IR Data Structures:
+      - Core IR Data Structures: api/ir/index.md
+      - Attribute: api/ir/attribute.md
+      - SSAValue: api/ir/ssa_value.md
+      - IRNode: api/ir/ir_node.md
+      - Operation: api/ir/operation.md
+      - Block: api/ir/block.md
+      - Region: api/ir/region.md
+      - Dialect: api/ir/dialect.md
+  - Code Reference: reference/index.md
+  - Guides:
+    - MLIR Interoperation: guides/mlir_interoperation.md
diff --git a/pyproject.toml b/pyproject.toml
index 91003c44d5..8c511d5730 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -34,8 +34,9 @@ dev = [
     "pyright==1.1.392.post0",
 ]
 docs = [
-    "mkdocs>=1.6.1",
+    "mkdocs-gen-files>=0.5.0",
     "mkdocs-material>=9.5.49",
+    "mkdocs>=1.6.1",
     "mkdocstrings[python]>=0.27.0",
 ]
 gui = ["textual==1.0.0", "pyclip==0.7"]
diff --git a/scripts/gen_ref_pages.py b/scripts/gen_ref_pages.py
new file mode 100644
index 0000000000..7733bfb4e7
--- /dev/null
+++ b/scripts/gen_ref_pages.py
@@ -0,0 +1,49 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+from mkdocs_gen_files.nav import Nav
+
+nav = Nav()
+
+root = Path(__file__).parent.parent
+src = root / "xdsl"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+    elif parts[-1].startswith("_"):
+        continue
+    if not parts:
+        continue
+
+    if "ir" == parts[0]:
+        # IR is documented separately
+        continue
+
+    ident = ".".join(parts)
+
+    if ident in ("irdl.error",):
+        # TODO: rename error function, treated as circular reference
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        fd.write(f"::: xdsl.{ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/index.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
diff --git a/uv.lock b/uv.lock
index 331e321a89..00e344db48 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1205,6 +1205,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f4/4a/960c441950f98becfa5dd419adab20274939fd575ab848aee2c87e3599ac/mkdocs_autorefs-1.3.0-py3-none-any.whl", hash = "sha256:d180f9778a04e78b7134e31418f238bba56f56d6a8af97873946ff661befffb3", size = 17642 },
 ]
 
+[[package]]
+name = "mkdocs-gen-files"
+version = "0.5.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mkdocs" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/48/85/2d634462fd59136197d3126ca431ffb666f412e3db38fd5ce3a60566303e/mkdocs_gen_files-0.5.0.tar.gz", hash = "sha256:4c7cf256b5d67062a788f6b1d035e157fc1a9498c2399be9af5257d4ff4d19bc", size = 7539 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e7/0f/1e55b3fd490ad2cecb6e7b31892d27cb9fc4218ec1dab780440ba8579e74/mkdocs_gen_files-0.5.0-py3-none-any.whl", hash = "sha256:7ac060096f3f40bd19039e7277dd3050be9a453c8ac578645844d4d91d7978ea", size = 8380 },
+]
+
 [[package]]
 name = "mkdocs-get-deps"
 version = "0.2.0"
@@ -2873,6 +2885,7 @@ dev = [
 ]
 docs = [
     { name = "mkdocs" },
+    { name = "mkdocs-gen-files" },
     { name = "mkdocs-material" },
     { name = "mkdocstrings", extra = ["python"] },
 ]
@@ -2899,6 +2912,7 @@ requires-dist = [
     { name = "lit", marker = "extra == 'dev'", specifier = "<19.0.0" },
     { name = "marimo", marker = "extra == 'dev'", specifier = "==0.10.14" },
     { name = "mkdocs", marker = "extra == 'docs'", specifier = ">=1.6.1" },
+    { name = "mkdocs-gen-files", marker = "extra == 'docs'", specifier = ">=0.5.0" },
     { name = "mkdocs-material", marker = "extra == 'docs'", specifier = ">=9.5.49" },
     { name = "mkdocstrings", extras = ["python"], marker = "extra == 'docs'", specifier = ">=0.27.0" },
     { name = "nbconvert", marker = "extra == 'dev'", specifier = ">=7.7.2,<8.0.0" },