WIP docs: Migrate docs site from mkdocs-material to mdBook#18337
Open
hakman wants to merge 5 commits into
Open
WIP docs: Migrate docs site from mkdocs-material to mdBook#18337hakman wants to merge 5 commits into
hakman wants to merge 5 commits into
Conversation
Introduces a parallel mdBook-based docs build to evaluate replacing mkdocs-material. Stock mdBook v0.5.2, no preprocessors. Adds book.toml, docs/SUMMARY.md covering all current pages, hack/build-mdbook.sh to fetch the pinned binary, and Makefile targets build-docs-mdbook / live-docs-mdbook. Existing mkdocs build is untouched.
Replaces the 73 {{ kops_feature_table(...) }} call sites across 14
docs files with the equivalent rendered markdown tables, and deletes
the hack/mkdocs_macros/ Python module plus the mkdocs-macros-plugin
dependency. The mkdocs build still loads the macros plugin via
default settings for the few remaining Jinja escapes in
contributing/adding_a_feature.md; that escape syntax is cleaned up
in the Netlify cutover commit. mdBook needs no templating layer for
the inlined tables.
netlify.toml now runs hack/build-mdbook.sh instead of the mkdocs
Python pipeline, dropping the PYTHON_VERSION env. Netlify's default
pretty_urls handles legacy /foo/ paths against mdBook's /foo.html
output without per-page rewrites. Also unwraps the 22 remaining
{{ '...' }} mkdocs-macros Jinja escapes in adding_a_feature.md and
cluster_template.md so the embedded Go template snippets render
literally under mdBook.
Deletes mkdocs.yml, images/mkdocs/, docs/.pages and the Docker/pip-based docs pipeline. Renames the mdbook Makefile targets to the canonical live-docs / build-docs names, retargets the contributing docs at SUMMARY.md, and swaps the leftover .md-content selector in extra.css for mdBook's .content class.
mdbook serve was binding to 0.0.0.0 and then opening http://0.0.0.0:3000/ in the browser, which is unroutable. Switches to localhost and lets the user click the printed URL. Adds a PORT env var override for collisions.
k8s-ci-robot
added
the
do-not-merge/work-in-progress
k8s-ci-robot
added
cncf-cla: yes
Contributor
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
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
2 participants
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
Replaces the Python/mkdocs-material build with stock mdBook v0.5.2.
Drops the pip-based Alpine image and the custom Python macro plugin
in favor of a single ~50-line shell script that fetches a pinned binary.
Notes
kops_feature_table()calls inlined as static markdown tables.pretty_urlsresolves legacy/foo/paths to mdBook's/foo.html— no per-page redirects needed.MDBOOK_VERSIONinhack/build-mdbook.sh.Mostly done by Claude Opus
/cc @rifelpet @justinsb