[Docs] Refactoring, to bring .md to any page; plus, generate examples properly with correct repo edit URL; removed from a legacy llmstxt mkdocs plugin; added skill.md stub (content to be added)

peterschmidt85 · peterschmidt85 · commit a34679d9fb63 · 2026-01-31T01:20:39.000+01:00
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/dev-environments.md b/docs/docs/concepts/dev-environments.md
@@ -3,7 +3,7 @@
 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/services.md b/docs/docs/concepts/services.md
@@ -3,7 +3,7 @@
 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
@@ -3,7 +3,7 @@
 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/index.md b/docs/docs/index.md
@@ -13,7 +13,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 +35,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)
diff --git a/docs/docs/installation.md b/docs/docs/installation.md
@@ -63,11 +63,11 @@ The server can run on your laptop or any environment with access to the cloud an
         
     </div>
 
-For more details on server deployment options, see the [Server deployment](../guides/server-deployment.md) guide.
+For more details on server deployment options, see the [Server deployment](guides/server-deployment.md) guide.
 
 ### Configure backends
 
-> To orchestrate compute across GPU clouds or Kubernetes clusters, you need to configure [backends](../concepts/backends.md).
+> To orchestrate compute across GPU clouds or Kubernetes clusters, you need to configure [backends](concepts/backends.md).
 
 ## Set up the CLI
 
@@ -126,7 +126,7 @@ This configuration is stored in `~/.dstack/config.yml`.
 
 ### Check offers
 
-To verify that both the server and CLI are properly configured, use the [`dstack offer`](../reference/cli/dstack/offer.md#list-gpu-offers) command to list available GPU offers. If you don't see valid offers, ensure you've set up [backends](../concepts/backends.md).
+To verify that both the server and CLI are properly configured, use the [`dstack offer`](reference/cli/dstack/offer.md#list-gpu-offers) command to list available GPU offers. If you don't see valid offers, ensure you've set up [backends](concepts/backends.md).
 
 ??? info "Shell autocompletion"
 
@@ -195,8 +195,8 @@ To verify that both the server and CLI are properly configured, use the [`dstack
         > `autoload -Uz compinit && compinit`.
 
 !!! info "What's next?"
-    1. See [Backends](../concepts/backends.md)
-    2. Follow [Quickstart](../quickstart.md)
-    3. Check the [server deployment](../guides/server-deployment.md) guide
-    4. Browse [examples](../../examples.md)
+    1. See [Backends](concepts/backends.md)
+    2. Follow [Quickstart](quickstart.md)
+    3. Check the [server deployment](guides/server-deployment.md) guide
+    4. Browse [examples](../examples.md)
     5. Join the community via [Discord](https://discord.gg/u8SmfwPpMd)
diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md
@@ -1,7 +1,7 @@
 # Quickstart
 
 !!! info "Prerequsites"
-    Before using `dstack`, ensure you've [installed](installation/index.md) the server and the CLI.
+    Before using `dstack`, ensure you've [installed](installation.md) the server and the CLI.
 
 ## Create a fleet
 
diff --git a/docs/llms.txt b/docs/llms.txt
@@ -0,0 +1,48 @@
+# dstack
+
+> dstack is an open-source control plane for GPU provisioning and orchestration across GPU clouds, Kubernetes, and on-prem clusters.
+
+## Getting started
+
+- [Overview](https://dstack.ai/docs/index.md): What dstack is
+- [Installation](https://dstack.ai/docs/index.md): How to set up the dstack server and the dstack CLI
+- [Quickstart](https://dstack.ai/docs/quickstart.md): How to get started and submit your first run
+
+## Concepts
+
+- [Backends](https://dstack.ai/docs/concepts/backends.md): How to configure backends - to connect dstack to cloud providers, Kubernetes clusters, etc
+- [Fleets](https://dstack.ai/docs/concepts/fleets.md): How to create and manage fleets - required before submitting runs
+- [Dev environments](https://dstack.ai/docs/concepts/dev-environments.md): How to create dev environments - for interactive development using a desktop IDE
+- [Tasks](https://dstack.ai/docs/concepts/tasks.md): How to run tasks - for training or fine-tuning, including distributed tasks
+- [Services](https://dstack.ai/docs/concepts/services.md): How to deploy services - for model inference or web apps
+- [Volumes](https://dstack.ai/docs/concepts/volumes.md): How to manage volumes - for persistent storage or caching
+- [Gateways](https://dstack.ai/docs/concepts/gateways.md): How to manage gateways - enabling auto-scaling, rate limits, and custom domains
+- [Secrets](https://dstack.ai/docs/concepts/secrets.md): How to manage secrets - for API keys or other sensitive data
+- [Projects](https://dstack.ai/docs/concepts/projects.md): How to manage projects - for managing separate teams
+- [Metrics](https://dstack.ai/docs/concepts/metrics.md): How to access metrics - for monitoring of runs/jobs/fleets, hardware usage (e.g. GPU util), etc
+- [Events](https://dstack.ai/docs/concepts/events.md): How to access events - aka audit log - for tracking state changes, resource creation/deletion, etc
+
+## Guides
+
+- [Server deployment](https://dstack.ai/docs/guides/server-deployment.md): Detailed guide on how to deploy the dstack server
+- [Troubleshooting](https://dstack.ai/docs/guides/troubleshooting.md): Common issues and how to troubleshoot them
+- [Protips](https://dstack.ai/docs/guides/protips.md): Pro tips - tips and tricks to use dstack more efficiently
+
+## Examples
+
+- [TRL](https://dstack.ai/examples/single-node-training/trl.md): TRL
+- [Axolotl](https://dstack.ai/examples/single-node-training/axolotl.md): Axolotl
+- [TRL](https://dstack.ai/examples/distributed-training/trl.md): TRL
+- [Axolotl](https://dstack.ai/examples/distributed-training/axolotl.md): Axolotl
+- [Ray+RAGEN](https://dstack.ai/examples/distributed-training/ray-ragen.md): Ray+RAGEN
+- [NCCL/RCCL tests](https://dstack.ai/examples/clusters/nccl-rccl-tests.md): NCCL/RCCL tests
+- [SGLang](https://dstack.ai/examples/inference/sglang.md): SGLang
+- [vLLM](https://dstack.ai/examples/inference/vllm.md): vLLM
+- [NIM](https://dstack.ai/examples/inference/nim.md): NIM
+- [TensorRT-LLM](https://dstack.ai/examples/inference/trtllm.md): TensorRT-LLM
+
+## Accelerators
+
+- [AMD](https://dstack.ai/examples/accelerators/amd.md): AMD
+- [TPU](https://dstack.ai/examples/accelerators/tpu.md): TPU
+- [Tenstorrent](https://dstack.ai/examples/accelerators/tenstorrent.md): Tenstorrent
diff --git a/docs/skill.md b/docs/skill.md
@@ -0,0 +1,17 @@
+---
+name: dstack
+description: >-
+  dstack is an open-source control plane for GPU provisioning and orchestration across GPU clouds, Kubernetes, and on-prem clusters.
+---
+
+# dstack
+
+<!-- TODO (WIP)
+
+1. What dstack is, when to use this skill.
+2. Overview
+3. Configuration types with examples (and links to concept pages)
+4. Most useful commands (grouped by use-case)
+5. Troubleshooting commands
+
+ -->
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -13,6 +13,9 @@ edit_uri: edit/master/docs/
 #Copyright
 copyright: © 2025 dstack
 
+hooks:
+  - scripts/docs/hooks.py
+
 # Configuration
 theme:
   name: material
@@ -60,44 +63,6 @@ theme:
 
 # Plugins
 plugins:
-  - llmstxt-md:
-      enable_copy_button: false
-      sections:
-        Getting started:
-          - docs/index.md: What dstack is
-          - docs/installation/index.md: How to set up the dstack server and the dstack CLI
-          - docs/quickstart.md: How to get started and submit your first run
-        Concepts:
-          - docs/concepts/backends.md: How to configure backends - to connect dstack to cloud providers, Kubernetes clusters, etc
-          - docs/concepts/fleets.md: How to create and manage fleets - required before submitting runs
-          - docs/concepts/dev-environments.md: How to create dev environments - for interactive development using a desktop IDE
-          - docs/concepts/tasks.md: How to run tasks - for training or fine-tuning, including distributed tasks
-          - docs/concepts/services.md: How to deploy services - for model inference or web apps
-          - docs/concepts/volumes.md: How to manage volumes - for persistent storage or caching
-          - docs/concepts/gateways.md: How to manage gateways - enabling auto-scaling, rate limits, and custom domains
-          - docs/concepts/secrets.md: How to manage secrets - for API keys or other sensitive data
-          - docs/concepts/projects.md: How to manage projects - for managing separate teams
-          - docs/concepts/metrics.md: How to access metrics - for monitoring of runs/jobs/fleets, hardware usage (e.g. GPU util), etc
-          - docs/concepts/events.md: How to access events - aka audit log - for tracking state changes, resource creation/deletion, etc
-        Guides:
-          - docs/guides/server-deployment.md: Detailed guide on how to deploy the dstack server
-          - docs/guides/troubleshooting.md: Common issues and how to troubleshoot them
-          - docs/guides/protips.md: Pro tips - tips and tricks to use dstack more efficiently
-        Examples:
-          - examples/single-node-training/trl/index.md: TRL
-          - examples/single-node-training/axolotl/index.md: Axolotl
-          - examples/distributed-training/trl/index.md: TRL
-          - examples/distributed-training/axolotl/index.md: Axolotl
-          - examples/distributed-training/ray-ragen/index.md: Ray+RAGEN
-          - examples/clusters/nccl-rccl-tests/index.md: NCCL/RCCL tests
-          - examples/inference/sglang/index.md: SGLang
-          - examples/inference/vllm/index.md: vLLM
-          - examples/inference/nim/index.md: NIM
-          - examples/inference/trtllm/index.md: TensorRT-LLM
-        Accelerators:
-          - examples/accelerators/amd/index.md: AMD
-          - examples/accelerators/tpu/index.md: TPU
-          - examples/accelerators/tenstorrent/index.md: Tenstorrent
   - blog:
       blog_dir: blog
       post_url_format: "{slug}"
@@ -172,8 +137,8 @@ plugins:
         "docs/guides/migration.md": "docs/guides/upgrade.md"
   - typeset
   - gen-files:
+      # TODO: convert these to hooks
       scripts: # always relative to mkdocs.yml
-        - scripts/docs/gen_examples.py
         - scripts/docs/gen_cli_reference.py
         - scripts/docs/gen_openapi_reference.py
         - scripts/docs/gen_schema_reference.py
@@ -258,7 +223,7 @@ nav:
   - Docs:
       - Getting started:
           - Overview: docs/index.md
-          - Installation: docs/installation/index.md
+          - Installation: docs/installation.md
           - Quickstart: docs/quickstart.md
       - Concepts:
           - Backends: docs/concepts/backends.md
@@ -315,7 +280,8 @@ nav:
           - Plugins:
               - Python API: docs/reference/plugins/python/index.md
               - REST API: docs/reference/plugins/rest/index.md
-          - llms-full.txt: https://dstack.ai/llms-full.txt
+          - llms.txt: https://dstack.ai/llms.txt
+          - skill.md: https://dstack.ai/skill.md
   - Examples:
       - examples.md
       - Single-node training:
diff --git a/pyproject.toml b/pyproject.toml
@@ -161,7 +161,6 @@ dev = [
     "mkdocs-gen-files; python_version >= '3.11'",
     "mkdocstrings[python]; python_version >= '3.11'",
     "mkdocs-render-swagger-plugin; python_version >= '3.11'",
-    "mkdocs-llmstxt-md; python_version >= '3.11'"
 ]
 
 [project.optional-dependencies]
diff --git a/scripts/docs/hooks.py b/scripts/docs/hooks.py
