chore(docs): remove MkDocs site stack#156
Merged
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR removes the MkDocs Material + mike-based documentation site tooling (config, dependencies, and deploy workflow) while keeping the docs/ content as plain GitHub-rendered Markdown, and updates documentation references/CI accordingly.
Changes:
- Remove MkDocs site configuration, docs-site dependencies, and the GitHub Pages deployment workflow.
- Delete docs that only existed to support site versioning, plus the MkDocs-only asset.
- Update documentation/CI references to stop pointing at the now-removed published site and drop the CI frontmatter gate.
Reviewed changes
Copilot reviewed 10 out of 11 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Removed MkDocs site configuration (nav/theme/plugins). |
| docs/versioning.md | Removed doc that described MkDocs/mike versioned-site behavior. |
| docs/style.md | Updated docs authoring guidance to match “plain Markdown on GitHub” approach. |
| docs/requirements.txt | Removed docs-site Python dependencies (mkdocs-material, mike, pymdown-extensions). |
| docs/assets/dotty-hero.svg | Removed MkDocs-only logo/favicon asset. |
| CONTRIBUTING.md | Removed docs-site versioning contributor guidance. |
| COMPATIBILITY.md | Replaced published-site link with local-docs reference. |
| CHANGELOG.md | Removed changelog entry about versioned docs-site deployment. |
| .pre-commit-config.yaml | Updated check-yaml exclusions now that mkdocs.yml is gone. |
| .github/workflows/docs-deploy.yml | Removed GitHub Pages docs deployment workflow. |
| .github/workflows/ci.yml | Removed mkdocs/frontmatter-related CI checks and references. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| component exposes, what counts as a breaking change, and how to upgrade safely. | ||
|
|
||
| For protocol wire formats see [protocols.md](https://brettkinny.github.io/dotty-stackchan/latest/protocols/). | ||
| For protocol wire formats see `docs/protocols.md`. |
Comment on lines
24
to
27
| - id: check-yaml | ||
| exclude: '^(mkdocs\.yml|\.github/workflows/.*\.yml|firmware/)' | ||
| # mkdocs.yml uses python tags (!!python/name:...) that PyYAML | ||
| # safe_load can't resolve; GHA workflows use the same. yamllint | ||
| exclude: '^(\.github/workflows/.*\.yml|firmware/)' | ||
| # GHA workflows use tags PyYAML safe_load can't resolve; yamllint | ||
| # already lints them in CI. |
Comment on lines
24
to
+28
| yamllint \ | ||
| .config.yaml.template \ | ||
| docker-compose.yml.template \ | ||
| compose.all-in-one.yml \ | ||
| compose.local.override.yml \ | ||
| mkdocs.yml | ||
| compose.local.override.yml |
The MkDocs Material + `mike` versioned docs-site setup was unused overhead: a hand-synced nav, a GitHub Pages deploy workflow, and a CI job that failed builds over missing doc frontmatter — all for a site that duplicated docs that already render fine as plain markdown on GitHub. Removed: - mkdocs.yml, .github/workflows/docs-deploy.yml, docs/requirements.txt - docs/versioning.md (entirely about the mike/MkDocs site) - docs/assets/dotty-hero.svg (MkDocs logo/favicon only; README uses the bridge/assets copy) - CI frontmatter-check job + mkdocs.yml from the yaml-lint list Kept the docs/ frontmatter (harmless, GitHub renders it) and the root-file symlinks in docs/ (they back intra-docs relative links). Fixed references in CONTRIBUTING.md, COMPATIBILITY.md, CHANGELOG.md, and docs/style.md that pointed at the now-dead published site. Note: the gh-pages branch and the repo's GitHub Pages setting are untouched — delete them manually if no longer wanted. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
BrettKinny
force-pushed
the
worktree-remove-mkdocs
branch
from
a7fbfe7 to
ed7d003
Compare
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
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.
What
Strips out the MkDocs Material +
mikeversioned docs-site stack. The docs underdocs/stay exactly as they are — they already render fine as plain markdown on GitHub — we're just removing the unused build/publish apparatus around them.Why
The site was maintenance overhead with no current payoff:
nav:inmkdocs.ymlthat had to be hand-synced on every doc add/rename,mikeon tag push),frontmatter-checkjob that could fail builds over a missing---block.In line with the broader "strip things back to reduce maintenance burden" effort.
Removed
mkdocs.yml.github/workflows/docs-deploy.ymldocs/requirements.txt(mkdocs-material,mike,pymdown-extensions)docs/versioning.md— entirely about the docs-site versioning modeldocs/assets/dotty-hero.svg— MkDocs logo/favicon only; README's hero uses the separatebridge/assets/dotty-hero.svgfrontmatter-checkjob, andmkdocs.ymlfrom theyaml-lintfile listKept / fixed
docs/(SETUP.md,ROADMAP.md, etc.) — real docs link to them relatively.CONTRIBUTING.md,COMPATIBILITY.md,CHANGELOG.md, anddocs/style.md.Follow-up (manual, out of scope)
The
gh-pagesbranch and the repo's Settings → Pages configuration are untouched. Delete the branch and disable Pages if the site is no longer wanted.🤖 Generated with Claude Code