Rename docs/ to mkdocs/, move examples under /docs/, inline source#3859
Merged
peterschmidt85 merged 7 commits intomasterfrom May 7, 2026
Merged
Rename docs/ to mkdocs/, move examples under /docs/, inline source#3859peterschmidt85 merged 7 commits intomasterfrom
peterschmidt85 merged 7 commits intomasterfrom
Conversation
added 5 commits
May 6, 2026 17:01
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 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.
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.
6 tasks
added 2 commits
May 7, 2026 11:49
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
peterschmidt85
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/tomkdocs/for clarity (was confusingly nested asdocs/docs/; nowmkdocs/docs/reads naturally as "in mkdocs sources, the /docs/ URL section")mkdocs/examples/tomkdocs/docs/examples/, also move the Examples nav from a separate top-level menu into Docs for better visibility — URLs change from/examples/...to/docs/examples/...(with redirects from old paths)examples/into the page md undermkdocs/docs/examples/to make examples more maintainable and simplify working with docs (drops the build-time README → index materialization hook)🤖 Generated with Claude Code