dstackai · peterschmidt85 · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
@@ -23,3 +23,4 @@ jobs:
           name: site
           path: site
           retention-days: 1
+          include-hidden-files: true
diff --git a/.gitignore b/.gitignore
@@ -26,3 +26,4 @@ uv.lock
 /src/dstack/_internal/server/statics
 
 profiling_results.html
+docs/docs/reference/api/rest/openapi.json
diff --git a/contributing/DOCS.md b/contributing/DOCS.md
@@ -47,3 +47,106 @@ If you want to build static files, you can use the following command:
 ```shell
 uv run mkdocs build -s
 ```
+
+## Documentation build system
+
+The documentation uses a custom build system with MkDocs hooks to generate various files dynamically.
+
+### Build hooks
+
+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
+
+Files in `docs/reference/**/*.md` can use `#SCHEMA#` placeholders that are expanded with generated schema documentation during the build.
+
+#### 3. llms.txt generation
+
+Two files are generated for LLM consumption:
+
+- **llms.txt**: Structured overview of documentation with titles and descriptions
+  - Generated from mkdocs nav structure
+  - Includes sections: Getting started, Concepts, Guides, Examples
+  - Excludes: Reference section
+  - Configuration: `scripts/docs/gen_llms_files.py` (INCLUDE_SECTIONS, EXCLUDE_SECTIONS)
+
+- **llms-full.txt**: Full concatenation of all pages from llms.txt
+  - Contains complete markdown content of all included pages
+
+The generation logic is in `scripts/docs/gen_llms_files.py` and uses:
+- `site_name`, `site_description`, `site_url` from `mkdocs.yml`
+- Page titles from mkdocs nav structure
+- Page descriptions from markdown frontmatter
+
+**Adding descriptions**: To add descriptions to pages, add YAML frontmatter:
+
+```yaml
+---
+title: Page Title
+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`).
+
+#### 4. Skills discovery
+
+The build creates `.well-known/skills/` directory structure for skills discovery:
+- Reads `skills/dstack/SKILL.md`
+- Parses name and description from frontmatter
+- Generates `.well-known/skills/index.json`
+- Copies SKILL.md to both `.well-known/skills/dstack/` and site root
+
+### File structure
+
+```
+docs/
+├── docs/                    # Main documentation content
+│   ├── 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
+
+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
+
+skills/
+└── dstack/
+    └── SKILL.md            # Skills discovery content
+```
+
+### Testing changes
+
+When modifying the build system:
+
+1. Test local build: `uv run mkdocs build -s`
+2. Check generated files in `site/`:
+   - `site/llms.txt`
+   - `site/llms-full.txt`
+   - `site/.well-known/skills/index.json`
+3. Verify example pages render correctly
+4. Check that descriptions appear in llms.txt
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/blog/posts/0_20.md b/docs/blog/posts/0_20.md
@@ -121,7 +121,7 @@ While the update introduces breaking changes, 0.19.* CLIs remain compatible with
 
 ## What's next
 
-1. Follow the [Installation](../../docs/installation/index.md) guide
+1. Follow the [Installation](../../docs/installation.md) guide
 2. Try the [Quickstart](../../docs/quickstart.md)
 3. Report issues on [GitHub](https://github.com/dstackai/dstack/issues)
 4. Ask questions on [Discord](https://discord.gg/u8SmfwPpMd)
diff --git a/docs/blog/posts/digitalocean-and-amd-dev-cloud.md b/docs/blog/posts/digitalocean-and-amd-dev-cloud.md
@@ -71,7 +71,7 @@ $ dstack server
 
 </div>
 
-For more details, see [Installation](../../docs/installation/index.md).
+For more details, see [Installation](../../docs/installation.md).
 
 Use the `dstack` CLI to
 manage [dev environments](../../docs/concepts/dev-environments.md), [tasks](../../docs/concepts/tasks.md),

diff --git a/docs/blog/posts/dstack-sky.md b/docs/blog/posts/dstack-sky.md
@@ -69,7 +69,7 @@ Continue? [y/n]:
 </div>
 
 !!! info "Backends"
-    `dstack Sky` supports the same [backends](../../docs/installation/index.md) as the open-source version, except that you
+    `dstack Sky` supports the same [backends](../../docs/installation.md) as the open-source version, except that you
     don't need to set them up. By default, it uses all supported backends.
 
 You can use both on-demand and spot instances without needing to manage quotas, as they are automatically handled

diff --git a/docs/blog/posts/hotaisle.md b/docs/blog/posts/hotaisle.md
@@ -80,7 +80,7 @@ $ dstack server
 
 </div>
 
-For more details, see [Installation](../../docs/installation/index.md).
+For more details, see [Installation](../../docs/installation.md).
 
 Use the `dstack` CLI to
 manage [dev environments](../../docs/concepts/dev-environments.md), [tasks](../../docs/concepts/tasks.md),

diff --git a/docs/blog/posts/nebius.md b/docs/blog/posts/nebius.md
@@ -77,7 +77,7 @@ $ dstack server
 
 </div>
 
-For more details, refer to [Installation](../../docs/installation/index.md).
+For more details, refer to [Installation](../../docs/installation.md).
 
 Use the `dstack` CLI to
 manage [dev environments](../../docs/concepts/dev-environments.md), [tasks](../../docs/concepts/tasks.md),

diff --git a/docs/blog/posts/nvidia-and-amd-on-vultr.md b/docs/blog/posts/nvidia-and-amd-on-vultr.md
@@ -65,7 +65,7 @@ projects:
 
 </div>
 
-For more details, refer to [Installation](../../docs/installation/index.md).
+For more details, refer to [Installation](../../docs/installation.md).
 
 > Interested in fine-tuning or deploying DeepSeek on Vultr? Check out the corresponding [example](../../examples/llms/deepseek/index.md).
 

diff --git a/docs/docs/concepts/backends.md b/docs/docs/concepts/backends.md
@@ -1,3 +1,8 @@
+---
+title: Backends
+description: Configuring cloud providers and Kubernetes clusters
+---
+
 # Backends
 
 Backends allow `dstack` to provision fleets across GPU clouds or Kubernetes clusters.

diff --git a/docs/docs/concepts/dev-environments.md b/docs/docs/concepts/dev-environments.md
@@ -1,9 +1,14 @@
+---
+title: Dev environments
+description: Provisioning remote instances for cloud-based development
+---
+
 # Dev environments
 
 A dev environment lets you provision an instance and access it with your desktop IDE.
 
 ??? info "Prerequisites"
-    Before running a dev environment, make sure you’ve [installed](../installation/index.md) the server and CLI, and created a [fleet](fleets.md).
+    Before running a dev environment, make sure you’ve [installed](../installation.md) the server and CLI, and created a [fleet](fleets.md).
 
 ## Apply a configuration
 

diff --git a/docs/docs/concepts/events.md b/docs/docs/concepts/events.md
@@ -1,3 +1,8 @@
+---
+title: Events
+description: Auditing resource state changes and operations
+---
+
 # Events
 
 Events provide a chronological record of notable state changes and operations affecting `dstack` resources. They are designed for auditing, debugging, and understanding the lifecycle of runs, jobs, fleets, and other resources.

diff --git a/docs/docs/concepts/fleets.md b/docs/docs/concepts/fleets.md
@@ -1,3 +1,8 @@
+---
+title: Fleets
+description: Managing pools of compute instances
+---
+
 # Fleets
 
 Before submitting runs, you must create a fleet. Fleets act as both pools of instances and templates for how those instances are provisioned.

diff --git a/docs/docs/concepts/gateways.md b/docs/docs/concepts/gateways.md
@@ -1,3 +1,8 @@
+---
+title: Gateways
+description: Managing ingress traffic and endpoints for services
+---
+
 # Gateways
 
 Gateways manage ingress traffic for running [services](services.md), handle auto-scaling and rate limits, enable HTTPS, and allow you to configure a custom domain. They also support custom routers, such as the [SGLang Model Gateway](https://docs.sglang.ai/advanced_features/router.html#).

diff --git a/docs/docs/concepts/metrics.md b/docs/docs/concepts/metrics.md
@@ -1,3 +1,8 @@
+---
+title: Metrics
+description: Tracking and monitoring system metrics
+---
+
 # Metrics
 
 `dstack` automatically tracks essential metrics, which you can access via the CLI and UI.

diff --git a/docs/docs/concepts/projects.md b/docs/docs/concepts/projects.md
@@ -1,3 +1,8 @@
+---
+title: Projects
+description: Organizing teams and isolating resources
+---
+
 # Projects
 
 Projects enable the isolation of different teams and their resources. Each project can configure its own backends and

diff --git a/docs/docs/concepts/secrets.md b/docs/docs/concepts/secrets.md
@@ -1,3 +1,8 @@
+---
+title: Secrets
+description: Managing sensitive values and credentials
+---
+
 # Secrets
 
 Secrets allow centralized management of sensitive values such as API keys and credentials. They are project-scoped, managed by project admins, and can be referenced in run configurations to pass sensitive values to runs in a secure manner.

diff --git a/docs/docs/concepts/services.md b/docs/docs/concepts/services.md
@@ -1,9 +1,14 @@
+---
+title: Services
+description: Deploying models and web apps as endpoints
+---
+
 # Services
 
 Services allow you to deploy models or web apps as secure and scalable endpoints.
 
 ??? info "Prerequisites"
-    Before running a service, make sure you’ve [installed](../installation/index.md) the server and CLI, and created a [fleet](fleets.md).
+    Before running a service, make sure you’ve [installed](../installation.md) the server and CLI, and created a [fleet](fleets.md).
 
 ## Apply a configuration
 

diff --git a/docs/docs/concepts/tasks.md b/docs/docs/concepts/tasks.md
@@ -1,9 +1,14 @@
+---
+title: Tasks
+description: Running commands for training and batch processing
+---
+
 # Tasks
 
 A task allows you to run arbitrary commands on one or more nodes. They are best suited for jobs like training or batch processing.
 
 ??? info "Prerequisites"
-    Before running a task, make sure you’ve [installed](../installation/index.md) the server and CLI, and created a [fleet](fleets.md).
+    Before running a task, make sure you’ve [installed](../installation.md) the server and CLI, and created a [fleet](fleets.md).
 
 ## Apply a configuration
 

diff --git a/docs/docs/concepts/volumes.md b/docs/docs/concepts/volumes.md
@@ -1,3 +1,8 @@
+---
+title: Volumes
+description: Managing persistent data storage
+---
+
 # Volumes
 
 Volumes enable data persistence between runs of dev environments, tasks, and services. 

diff --git a/docs/docs/guides/protips.md b/docs/docs/guides/protips.md
@@ -1,3 +1,8 @@
+---
+title: Protips
+description: Tips and tricks for using dstack efficiently
+---
+
 # Protips
 
 Below are tips and tricks to use `dstack` more efficiently.

diff --git a/docs/docs/guides/server-deployment.md b/docs/docs/guides/server-deployment.md
@@ -1,3 +1,8 @@
+---
+title: Server Deployment
+description: Deploying the dstack server
+---
+
 The `dstack` server can run on your laptop or any environment with access to the cloud and on-prem clusters you plan to use.
 
 The minimum hardware requirements for running the server are 1 CPU and 1GB of RAM.

diff --git a/docs/docs/guides/troubleshooting.md b/docs/docs/guides/troubleshooting.md
@@ -1,3 +1,8 @@
+---
+title: Troubleshooting
+description: Common issues and how to resolve them
+---
+
 # Troubleshooting
 
 ## Reporting issues

diff --git a/docs/docs/guides/upgrade.md b/docs/docs/guides/upgrade.md
@@ -1,3 +1,8 @@
+---
+title: Upgrade
+description: Upgrading to newer versions of dstack
+---
+
 # Upgrade guide
 
 <!-- TODO: Add general sections on how to migrate to newer releases and how major and minor versions compatibility  and deprecation policy is handled -->

diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -1,3 +1,8 @@
+---
+title: What is dstack?
+description: Introduction to dstack and how it works
+---
+
 # What is dstack?
 
 `dstack` is a unified control plane for GPU provisioning and orchestration that works with any GPU cloud, Kubernetes, or on-prem clusters. 
@@ -13,7 +18,7 @@ It streamlines development, training, and inference, and is compatible with any
 
 #### 1. Set up the server
 
-> Before using `dstack`, ensure you've [installed](installation/index.md) the server, or signed up for [dstack Sky](https://sky.dstack.ai).
+> Before using `dstack`, ensure you've [installed](installation.md) the server, or signed up for [dstack Sky](https://sky.dstack.ai).
 
 #### 2. Define configurations
 
@@ -35,7 +40,7 @@ Apply the configuration either via the `dstack apply` CLI command (or through a
 port-forwarding, ingress, and more.
 
 !!! info "Where do I start?"
-    1. Proceed to [installation](installation/index.md)
+    1. Proceed to [installation](installation.md)
     2. See [quickstart](quickstart.md)
     3. Browse [examples](/examples)
     4. Join [Discord](https://discord.gg/u8SmfwPpMd)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -26,3 +26,4 @@ uv.lock
		/src/dstack/_internal/server/statics

		profiling_results.html
		docs/docs/reference/api/rest/openapi.json
-Original file line number
+Diff line change
@@ Expand Up / @@ -65,7 +65,7 @@ projects: @@
     </div>
-    For more details, refer to [Installation](../../docs/installation/index.md).
+    For more details, refer to [Installation](../../docs/installation.md).
     > Interested in fine-tuning or deploying DeepSeek on Vultr? Check out the corresponding [example](../../examples/llms/deepseek/index.md).
@@ Expand Down @@