Rename docs/ to mkdocs/, move examples under /docs/, inline source (#3859)

* Inline example source code into docs pages

Drop the mkdocs hook that materialized examples/<path>/README.md into
docs/examples/<path>/index.md stubs at build time. Move the 20 navigated
example READMEs directly into docs/examples/<path>.md (flat layout, no
per-example subdirectory) and delete the parallel .dstack.yml configs
since their content is already inline in the markdown. The two GCP NCCL
test yamls that were only referenced via dead "Source code" admonitions
are now inlined into their respective tabs.

Within the moved pages, convert absolute https://dstack.ai/(docs|examples)
links to relative .md paths so mkdocs strict mode validates them.

Non-navigated examples (misc/, llms/, server-deployment/, plugins/,
single-node-training/{qlora,optimum-tpu}, the AMD subdirs, etc.) are
left untouched for a later pass.

* Move examples under /docs/, merge single and distributed training

- Move docs/examples/ to docs/docs/examples/ so URLs become /docs/examples/...
  instead of /examples/.... The old /examples/<cat>/<name>/ URLs continue to
  work via redirects, including the recently-published /docs/examples/
  {single-node-training,distributed-training}/ paths.
- Merge "Single-node training" and "Distributed training" example sections
  into a single "Training" section. TRL and Axolotl pages now contain both
  variants under top-level "Single-node training" and "Distributed training"
  H2 sections; Ray+RAGEN moves over unchanged.
- Convert remaining absolute https://dstack.ai/(docs|examples)/... links to
  relative .md links throughout the moved example pages and the concept docs
  that point into them. Drop dead /docs/guides/{clusters,kubernetes} links
  (target pages were removed earlier) and replace with anchor links to the
  Kubernetes backend / cluster placement sections where appropriate.
- Inline two GCP NCCL test yamls (a3mega-nccl-tests, a3high-nccl-tests) that
  were previously referenced via dead "Source code" admonitions.

* Drop redirect that collides with the real AMD example page

The redirect source 'docs/examples/accelerators/amd/index.md' is now the
canonical URL of the moved AMD example page, so the redirect plugin was
overwriting the real page's index.html with a self-referencing redirect,
producing an infinite loop.

* Add Accelerators link to footer Examples section

* Re-ordered top menu (moved Blog to the end)

* Rename docs/ to mkdocs/ and extract just recipes

The mkdocs source dir is now mkdocs/, and the previously-confusing
docs/docs/ nesting becomes mkdocs/docs/ (read: "in mkdocs sources,
the /docs/ URL section").

- mkdocs.yml: explicit docs_dir: mkdocs, plus custom_dir, cards_layout_dir,
  pymdownx.snippets.base_path, edit_uri all repointed to mkdocs/
- scripts/docs/{gen_openapi_reference,gen_rest_plugin_spec_reference}.py
  output paths repointed to mkdocs/docs/...; also write a trailing
  newline so end-of-file-fixer doesn't fight with mkdocs serve
- .gitignore: openapi.json patterns repointed to mkdocs/docs/...; untrack
  the three generated openapi.json files (they're regenerated by the
  build and shouldn't be in git)
- .github/workflows/build.yml path filter updated to mkdocs/**
- README.md, AGENTS.md, contributing/{DOCS,BACKENDS}.md prose updated
- .justfile: extract docs recipes into mkdocs/.justfile (mkdocs-serve,
  mkdocs-build) following the same pattern as runner/ and frontend/;
  drop -w examples (no longer needed) and add --livereload to work
  around mkdocs live-reload bugs

* Apply ruff import-sorting fixes to docs gen scripts

---------

Co-authored-by: Andrey Cheptsov <andrey.cheptsov@github.com>

Author: peterschmidt85

.github/workflows/build.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - "master"
     paths-ignore:
-      - "docs/**"
+      - "mkdocs/**"
       - "mkdocs.yml"
   pull_request:
     branches:

.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

.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"

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).

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>

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
 

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