@@ -47,3 +47,106 @@ If you want to build static files, you can use the following command:
4747``` shell
4848uv run mkdocs build -s
4949```
50+
51+ ## Documentation build system
52+
53+ The documentation uses a custom build system with MkDocs hooks to generate various files dynamically.
54+
55+ ### Build hooks
56+
57+ The build process is customized via hooks in ` scripts/docs/hooks.py ` :
58+
59+ #### 1. Example materialization
60+
61+ Example pages like ` examples/single-node-training/trl/index.md ` are stubs that reference ` README.md ` files in the repository root:
62+ - ** Stub location** : ` docs/examples/single-node-training/trl/index.md `
63+ - ** Content source** : ` examples/single-node-training/trl/README.md `
64+
65+ During the build, the hook reads the README content and uses it for rendering the HTML page.
66+
67+ #### 2. Schema reference expansion
68+
69+ Files in ` docs/reference/**/*.md ` can use ` #SCHEMA# ` placeholders that are expanded with generated schema documentation during the build.
70+
71+ #### 3. llms.txt generation
72+
73+ Two files are generated for LLM consumption:
74+
75+ - ** llms.txt** : Structured overview of documentation with titles and descriptions
76+ - Generated from mkdocs nav structure
77+ - Includes sections: Getting started, Concepts, Guides, Examples
78+ - Excludes: Reference section
79+ - Configuration: ` scripts/docs/gen_llms_files.py ` (INCLUDE_SECTIONS, EXCLUDE_SECTIONS)
80+
81+ - ** llms-full.txt** : Full concatenation of all pages from llms.txt
82+ - Contains complete markdown content of all included pages
83+
84+ The generation logic is in ` scripts/docs/gen_llms_files.py ` and uses:
85+ - ` site_name ` , ` site_description ` , ` site_url ` from ` mkdocs.yml `
86+ - Page titles from mkdocs nav structure
87+ - Page descriptions from markdown frontmatter
88+
89+ ** Adding descriptions** : To add descriptions to pages, add YAML frontmatter:
90+
91+ ``` yaml
92+ ---
93+ title : Page Title
94+ description : Short description of what this page covers
95+ ---
96+ ```
97+
98+ For examples, add frontmatter to the ` README.md ` files in the repository root (e.g., ` examples/single-node-training/trl/README.md ` ).
99+
100+ #### 4. Skills discovery
101+
102+ The build creates ` .well-known/skills/ ` directory structure for skills discovery:
103+ - Reads ` skills/dstack/SKILL.md `
104+ - Parses name and description from frontmatter
105+ - Generates ` .well-known/skills/index.json `
106+ - Copies SKILL.md to both ` .well-known/skills/dstack/ ` and site root
107+
108+ ### File structure
109+
110+ ```
111+ docs/
112+ ├── docs/ # Main documentation content
113+ │ ├── index.md # Getting started
114+ │ ├── installation.md
115+ │ ├── quickstart.md
116+ │ ├── concepts/ # Concept pages
117+ │ ├── guides/ # How-to guides
118+ │ └── reference/ # API reference (schema expansion)
119+ ├── examples/ # Example stub files (index.md)
120+ │ └── single-node-training/
121+ │ └── trl/
122+ │ └── index.md # Stub referencing root README
123+ └── overrides/ # Theme customization
124+
125+ examples/ # Example content (repository root)
126+ └── single-node-training/
127+ └── trl/
128+ ├── README.md # Actual content with frontmatter
129+ └── train.dstack.yml
130+
131+ scripts/docs/
132+ ├── hooks.py # MkDocs build hooks
133+ ├── gen_llms_files.py # llms.txt generation
134+ ├── gen_schema_reference.py # Schema expansion
135+ └── gen_cli_reference.py # CLI reference generation
136+
137+ skills/
138+ └── dstack/
139+ └── SKILL.md # Skills discovery content
140+ ```
141+
142+ ### Testing changes
143+
144+ When modifying the build system:
145+
146+ 1 . Test local build: ` uv run mkdocs build -s `
147+ 2 . Check generated files in ` site/ ` :
148+ - ` site/llms.txt `
149+ - ` site/llms-full.txt `
150+ - ` site/.well-known/skills/index.json `
151+ 3 . Verify example pages render correctly
152+ 4 . Check that descriptions appear in llms.txt
0 commit comments