dstackai · peterschmidt85 · May 7, 2026 · May 6, 2026 · May 6, 2026 · May 6, 2026
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -5,7 +5,7 @@ on:
     branches:
       - "master"
     paths-ignore:
-      - "docs/**"
+      - "mkdocs/**"
       - "mkdocs.yml"
   pull_request:
     branches:

diff --git a/.gitignore b/.gitignore
@@ -26,6 +26,7 @@ uv.lock
 /src/dstack/_internal/server/statics
 
 profiling_results.html
-docs/docs/reference/api/http/openapi.json
-docs/docs/reference/api/rest/openapi.json
-docs/docs/reference/plugins/rest/rest_plugin_openapi.json
+
+mkdocs/docs/reference/api/http/openapi.json
+mkdocs/docs/reference/api/rest/openapi.json
+mkdocs/docs/reference/plugins/rest/rest_plugin_openapi.json
diff --git a/.justfile b/.justfile
@@ -5,7 +5,9 @@
 # Run `just` to see all available commands.
 #
 # Components:
-# * runner/justfile – Building and uploading dstack runner and shim
+# * runner/.justfile – Building and uploading dstack runner and shim
+# * frontend/.justfile – Building and running the frontend
+# * mkdocs/.justfile – Building and previewing the docs site
 
 default:
     @just --list
@@ -16,5 +18,4 @@ import "runner/.justfile"
 
 import "frontend/.justfile"
 
-docs-serve:
-    uv run mkdocs serve --livereload -w examples -s
+import "mkdocs/.justfile"
diff --git a/AGENTS.md b/AGENTS.md
@@ -4,7 +4,7 @@
 - Core Python package lives in `src/dstack`; internal modules (including server) sit under `_internal`, API surfaces under `api`, and plugin integrations under `plugins`.
 - Tests reside in `src/tests` and mirror package paths; add new suites alongside the code they cover.
 - Frontend lives in `frontend` (React/webpack) and is built into `src/dstack/_internal/server/statics`.
-- Docs sources are in `docs` with extra contributor notes in `contributing/*.md`; examples for users sit in `examples/`.
+- Docs sources are in `mkdocs/docs/` with extra contributor notes in `contributing/*.md`.
 
 ## Build, Test, and Development Commands
 - Install deps (editable package with extras): `uv sync --all-extras` (uses `.venv` in repo).

diff --git a/README.md b/README.md
@@ -2,8 +2,8 @@
 <h2>
   <a target="_blank" href="https://dstack.ai">
     <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dstackai/dstack/master/docs/assets/images/dstack-logo-dark.svg"/>
-      <img alt="dstack" src="https://raw.githubusercontent.com/dstackai/dstack/master/docs/assets/images/dstack-logo.svg" width="350px"/>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dstackai/dstack/master/mkdocs/assets/images/dstack-logo-dark.svg"/>
+      <img alt="dstack" src="https://raw.githubusercontent.com/dstackai/dstack/master/mkdocs/assets/images/dstack-logo.svg" width="350px"/>
     </picture>
   </a>
 </h2>

diff --git a/contributing/BACKENDS.md b/contributing/BACKENDS.md
@@ -160,8 +160,8 @@ If instances in the backend take more than 10 minutes to start, override the def
 
 ### 2.10. Document the backend
 
-Add the backend to the [Concepts->Backends](https://github.com/dstackai/dstack/blob/master/docs/docs/concepts/backends.md
-) page and the [server/comfig.yml](https://github.com/dstackai/dstack/blob/master/docs/docs/reference/server/config.yml.md) reference.
+Add the backend to the [Concepts->Backends](https://github.com/dstackai/dstack/blob/master/mkdocs/docs/concepts/backends.md
+) page and the [server/comfig.yml](https://github.com/dstackai/dstack/blob/master/mkdocs/docs/reference/server/config.yml.md) reference.
 
 ## 3. Appendix
 

diff --git a/contributing/DOCS.md b/contributing/DOCS.md
@@ -39,9 +39,11 @@ uv run pre-commit install
 To preview the documentation, run the follow command:
 
 ```shell
-uv run mkdocs serve -w examples -s
+uv run mkdocs serve --livereload -s
 ```
 
+The `--livereload` flag is required to work around live-reload bugs in recent `mkdocs` versions.
+
 If you want to build static files, you can use the following command:
 
 ```shell
@@ -57,7 +59,6 @@ The documentation uses a custom build system with MkDocs hooks to generate vario
 Use these in `.envrc` to disable expensive docs regeneration, especially during `mkdocs serve` auto-reload. Set any of them to disable the corresponding artifact.
 
 ```shell
-export DSTACK_DOCS_DISABLE_EXAMPLES=1
 export DSTACK_DOCS_DISABLE_LLM_TXT=1
 export DSTACK_DOCS_DISABLE_CLI_REFERENCE=1
 export DSTACK_DOCS_DISABLE_YAML_SCHEMAS=1
@@ -69,19 +70,11 @@ export DSTACK_DOCS_DISABLE_REST_PLUGIN_SPEC_REFERENCE=1
 
 The build process is customized via hooks in `scripts/docs/hooks.py`:
 
-#### 1. Example materialization
-
-Example pages like `examples/single-node-training/trl/index.md` are stubs that reference `README.md` files in the repository root:
-- **Stub location**: `docs/examples/single-node-training/trl/index.md`
-- **Content source**: `examples/single-node-training/trl/README.md`
-
-During the build, the hook reads the README content and uses it for rendering the HTML page.
-
-#### 2. Schema reference expansion
+#### 1. Schema reference expansion
 
 Files in `docs/reference/**/*.md` can use `#SCHEMA#` placeholders that are expanded with generated schema documentation during the build.
 
-#### 3. llms.txt generation
+#### 2. llms.txt generation
 
 Two files are generated for LLM consumption:
 
@@ -108,9 +101,9 @@ description: Short description of what this page covers
 ---
 ```
 
-For examples, add frontmatter to the `README.md` files in the repository root (e.g., `examples/single-node-training/trl/README.md`).
+For examples, add frontmatter to the page files (e.g., `mkdocs/docs/examples/training/trl.md`).
 
-#### 4. Skills discovery
+#### 3. Skills discovery
 
 The build creates `.well-known/skills/` directory structure for skills discovery:
 - Reads `skills/dstack/SKILL.md`
@@ -121,35 +114,32 @@ The build creates `.well-known/skills/` directory structure for skills discovery
 ### File structure
 
 ```
-docs/
-├── docs/                    # Main documentation content
-│   ├── index.md            # Getting started
+mkdocs/                         # docs_dir for the mkdocs site
+├── index.md                    # Homepage
+├── docs/                       # /docs/ URL section
+│   ├── index.md                # Getting started
 │   ├── installation.md
 │   ├── quickstart.md
-│   ├── concepts/           # Concept pages
-│   ├── guides/             # How-to guides
-│   └── reference/          # API reference (schema expansion)
-├── examples/               # Example stub files (index.md)
-│   └── single-node-training/
-│       └── trl/
-│           └── index.md    # Stub referencing root README
-└── overrides/              # Theme customization
-
-examples/                    # Example content (repository root)
-└── single-node-training/
-    └── trl/
-        ├── README.md       # Actual content with frontmatter
-        └── train.dstack.yml
+│   ├── concepts/               # Concept pages
+│   ├── guides/                 # How-to guides
+│   ├── reference/              # API reference (schema expansion)
+│   └── examples/               # Example pages (inline source code)
+│       └── training/
+│           └── trl.md          # Page content with frontmatter
+├── blog/                       # Blog posts
+├── overrides/                  # Theme customization
+├── layouts/                    # Social card layouts
+└── assets/                     # Stylesheets, images, fonts
 
 scripts/docs/
-├── hooks.py                # MkDocs build hooks
-├── gen_llms_files.py       # llms.txt generation
-├── gen_schema_reference.py # Schema expansion
-└── gen_cli_reference.py    # CLI reference generation
+├── hooks.py                    # MkDocs build hooks
+├── gen_llms_files.py           # llms.txt generation
+├── gen_schema_reference.py     # Schema expansion
+└── gen_cli_reference.py        # CLI reference generation
 
 skills/
 └── dstack/
-    └── SKILL.md            # Skills discovery content
+    └── SKILL.md                # Skills discovery content
 ```
 
 ### Testing changes

diff --git a/docs/examples/clusters/crusoe/index.md b/docs/examples/clusters/crusoe/index.md
diff --git a/docs/examples/clusters/gcp/index.md b/docs/examples/clusters/gcp/index.md
diff --git a/docs/examples/clusters/lambda/index.md b/docs/examples/clusters/lambda/index.md
diff --git a/docs/examples/clusters/nccl-rccl-tests/index.md b/docs/examples/clusters/nccl-rccl-tests/index.md
diff --git a/docs/examples/clusters/nebius/index.md b/docs/examples/clusters/nebius/index.md
diff --git a/docs/examples/distributed-training/axolotl/index.md b/docs/examples/distributed-training/axolotl/index.md
diff --git a/docs/examples/distributed-training/ray-ragen/index.md b/docs/examples/distributed-training/ray-ragen/index.md
diff --git a/docs/examples/distributed-training/trl/index.md b/docs/examples/distributed-training/trl/index.md
diff --git a/docs/examples/inference/nim/index.md b/docs/examples/inference/nim/index.md
diff --git a/docs/examples/inference/sglang/index.md b/docs/examples/inference/sglang/index.md
diff --git a/docs/examples/inference/trtllm/index.md b/docs/examples/inference/trtllm/index.md
diff --git a/docs/examples/inference/vllm/index.md b/docs/examples/inference/vllm/index.md
diff --git a/docs/examples/llms/deepseek/index.md b/docs/examples/llms/deepseek/index.md
diff --git a/docs/examples/llms/llama/index.md b/docs/examples/llms/llama/index.md
diff --git a/docs/examples/misc/docker-compose/index.md b/docs/examples/misc/docker-compose/index.md
diff --git a/docs/examples/models/deepseek-v4/index.md b/docs/examples/models/deepseek-v4/index.md
diff --git a/docs/examples/models/qwen36/index.md b/docs/examples/models/qwen36/index.md
diff --git a/docs/examples/models/wan22/index.md b/docs/examples/models/wan22/index.md
diff --git a/docs/examples/single-node-training/axolotl/index.md b/docs/examples/single-node-training/axolotl/index.md
diff --git a/docs/examples/single-node-training/trl/index.md b/docs/examples/single-node-training/trl/index.md
diff --git a/examples/accelerators/tenstorrent/.dstack.yml b/examples/accelerators/tenstorrent/.dstack.yml
diff --git a/examples/accelerators/tenstorrent/tt-inference-server.dstack.yml b/examples/accelerators/tenstorrent/tt-inference-server.dstack.yml
diff --git a/examples/accelerators/tenstorrent/tt-smi.dstack.yml b/examples/accelerators/tenstorrent/tt-smi.dstack.yml
diff --git a/examples/clusters/aws/fleet.dstack.yml b/examples/clusters/aws/fleet.dstack.yml
diff --git a/examples/clusters/gcp/a3-fleet.dstack.yml b/examples/clusters/gcp/a3-fleet.dstack.yml
diff --git a/examples/clusters/gcp/a3high-fleet.dstack.yml b/examples/clusters/gcp/a3high-fleet.dstack.yml
diff --git a/examples/clusters/gcp/a3high-nccl-tests.dstack.yml b/examples/clusters/gcp/a3high-nccl-tests.dstack.yml
diff --git a/examples/clusters/gcp/a3mega-nccl-tests.dstack.yml b/examples/clusters/gcp/a3mega-nccl-tests.dstack.yml
diff --git a/examples/clusters/gcp/a4-fleet.dstack.yml b/examples/clusters/gcp/a4-fleet.dstack.yml
diff --git a/examples/clusters/nccl-rccl-tests/nccl-tests.dstack.yml b/examples/clusters/nccl-rccl-tests/nccl-tests.dstack.yml