Attempt to rebuild docs build process, inspired by #6319 #6371

evankanderson · 2025-09-12T22:04:51Z

Proposed Changes

Rewrites the documentation building system to run mkdocs build exactly once, with all the files in the tree. The current build runs mdocs build N+2 times for the number of releases we have (N releases, plus "development" and "blog"), and forces our homepage, about, and community sites to live under https://knative.dev/docs because versioning.

I believe this is relatively complete, but we are stretching the capabilities of mkdocs. I think it's still worth it, but I wanted to get this generally-working checkpoint in before going further. (See also the unfortunate breakages that @rohan-019 had to deal with in #6319)

I discovered that awesome-pages-plugin had been replaced by awesome-nav, which has a few more features. One feature is being able to build up global nav from .nav.yaml files in directories. I used that to build up the nav for each subtree of the site separately.
I replaced a global environment variables with page metadata for things like Knative version and whether there is a newer version. The global environment variables weren't going to work well with a single mkdocs run.
Eventually, we probably want to move the documentation content to a sub-directory, but I used mv for testing. This is probably wrong; I ended up copying some images for now to avoid making weird break/fix changes.
I removed the extra "blog" build, which removed a lot of duplicated (or even never-referenced) files and images. That's the majority of the file status of this PR.
- This necessitated fixing some of the blog image URLs, which meant that I noticed a bunch didn't have alt text. I fixed those.
Because the top-level page got moved up to /, I needed to redo the redirects.yml. We also currently use this to redirect the top-level docs page to concepts/, but when we move the docs under a dedicated sub-directory, we should move that page up to the top level.
I needed to tweak the navigation templates in a few places. Logically, we have four levels of navigation:
- Content section at the top-most bar
- (docs-specific) Topic-specific tabs, under the topmost bar
- Between-page navigation on the left
- TOC / within-page navigation on the right.
I think this is generally correct, but there is definitely a lot. We might relocate the TOC navigation within the between-page nav (Material-Mkdocs has an option for this), but I didn't want to mess with it here. There's probably also some additional fixing to be done -- I think we may need to re-do the top nav bar to get it working well on mobile. I also didn't work on that, because this PR is nearly-unreviewable as is.

netlify · 2025-09-12T22:05:26Z

✅ Deploy Preview for knative ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`1f149a5`
🔍 Latest deploy log	https://app.netlify.com/projects/knative/deploys/68c878f1a13c1b00089d9200
😎 Deploy Preview	https://deploy-preview-6371--knative.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

evankanderson · 2025-09-12T22:06:41Z

@rohan-019, I'd love your review.

@Cali0707 or @dprotaso -- if you have some cycles, please take a look.

evankanderson · 2025-09-12T22:13:06Z

The mkdocs build --strict GitHub Action is failing because it's not running all our lovely custom build.sh logic that we use to produce a release. I'll see what I can do to fix that.

evankanderson · 2025-09-12T22:16:40Z

docs/install/operator/knative-with-operator-cli.md


        ```bash
-        kubectl apply --filename {{artifact(repo="net-contour",file="contour.yaml")}}
+        kubectl apply --filename {{artifact(repo="net-contour",org="knative-extensions",file="contour.yaml")}}


I noticed some build complaints trying to fetch these from the wrong place. If they offend, I can revert and offer these separately.

evankanderson · 2025-09-12T22:17:22Z

docs/stylesheets/extra.css


-#sub-nav li:nth-last-child(3), #sub-nav li:nth-last-child(2), #sub-nav li:nth-last-child(1) {
-  display: none;
-}
-
-
 /* bit of a hack to stop the banner taking space when empty */


This is how we hid the "blog" "about" and "community" nav items from the bar in the redesign. Sorry I missed this!

evankanderson · 2025-09-12T22:17:58Z

hack/build.sh

+# rm -rf $TEMP
+echo "Temp dir was: $TEMP"


I can put back this removal, but I found it helpful sometimes to poke into these temp directories while debugging.

evankanderson · 2025-09-12T22:18:39Z

hack/macros.py

+        # Don't try to version-match outside Knative-managed repos
+        if org not in ("knative", "knative-extensions"):
+            return f'https://github.com/{org}/{repo}/releases/latest/download/{file}'


Another attempt to avoid a bunch of build time complaints (though there are still a bunch of others that seem harmless but annoying).

evankanderson · 2025-09-12T22:19:25Z

mkdocs.yml

+  # Allow `.meta.yml` to define metadata for all pages below that directory.
+  # See https://squidfunk.github.io/mkdocs-material/plugins/meta/
+  meta:
+    enabled: true


We use this to set the version / outdated / sample branch fields for the versioned documentation in the shell script.

evankanderson · 2025-09-12T22:19:52Z

netlify.toml

@@ -6,7 +6,7 @@

 [build.environment]
  NODE_VERSION= "22"
-  PYTHON_VERSION = "3.9"
+  PYTHON_VERSION = "3.13"


awesome-pages needs at least 3.10, but I didn't see a good reason not to move past that point.

overrides/main.html

evankanderson · 2025-09-12T22:22:21Z

overrides/partials/header.html

@@ -97,7 +97,7 @@
        </a>
      </li>
      <li class="md-tabs__item">
-        <a href="/docs/about/testimonials/" class="md-tabs__link">
+        <a href="/about/testimonials/" class="md-tabs__link">


We may want to do something more sophisticated / reach out to the material mkdocs team to figure out a better solution for these top-level menu tabs. I'm not sure they were designed or thought through on mobile.

evankanderson · 2025-09-12T22:22:45Z

overrides/partials/nav.html

+  {# Create nav from the "section" of docs that we are in.
+     Some sections (about, community) are not versioned, while docs is. #}
+  {% set section = nav | selectattr("active") | first %}
+  {% if section %}
+    {% set nav = section %}
+  {% endif %}


This is the new bit, the rest is imported from upstream.

dprotaso · 2025-09-13T01:18:14Z

/lgtm
/approve
/hold for any other reviews

I did a pass through the preview and it looked fine (eg. the URLs paths work as expected). Feel free to unhold

As a follow up we might want to drop the the version picker on the home page (and other pages) when you're not looking at the docs

evankanderson · 2025-09-15T18:12:45Z

/lgtm /approve /hold for any other reviews

I did a pass through the preview and it looked fine (eg. the URLs paths work as expected). Feel free to unhold

As a follow up we might want to drop the the version picker on the home page (and other pages) when you're not looking at the docs

Oh, good point. Unfortunately, I think that may be tricky given that the version picker is added via TypeScript, which is built into a minified bundle: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/javascripts/integrations/version/index.ts#L151

We may be able to manually set config.version.provider to a string other than mike in the {% block config %} override, which looks like it should disable the selector. Let me see what I can do.

evankanderson · 2025-09-15T20:36:20Z

I fixed the GitHub Action and the version picker appearing on unversioned pages. I also chased down a number of Hugo shortcodes (in blog and smoketest.md) that never worked with mkdocs.

dprotaso · 2025-09-15T22:42:18Z

/hold cancel
/lgtm
/approve

knative-prow · 2025-09-15T22:42:27Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: dprotaso, evankanderson

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [dprotaso,evankanderson]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

…ive#6371) * Attempt to rebuild docs build process * Use a more modern python version * Fix strict verify, hide versions on unversioned pages

* Phase 1: Adding documentation metadata tags (#6274) * Add metadata tags for documentation * Add classification for about 2/3rds of docs (func + eventing) * Add classification for remainder of docs (serving+install) * Add mermaid support (#6327) * Publish threat model in documentation (#6263) * Publish threat model in documentation * Separate security contents a bit more, update link to threat model, update nav * Add a section on supply chain and SBOM/SLSA mitigation * Update threat model with feedback from David Hadas * Update introduction with content from davidhadas, add sections on controller and webhook functionality and update targets of threats * content tab fixes, added success output for kn func (#6367) * Add dry run section and take out old feature flag in serving (#6366) * add dry run section * drop mention of old feature flag * fix casing on nav * update docs to be more clear and include inline example --------- Co-authored-by: Dave Protasowski <[email protected]> * Attempt to rebuild docs build process, inspired by #6319 (#6371) * Attempt to rebuild docs build process * Use a more modern python version * Fix strict verify, hide versions on unversioned pages * Fix search with mkdocs typescript patches (vendored). (#6392) Hopefully, this can be fixed upstream via PR shortly. * Installation Doc Updates (#6395) * Installation Doc Updates Improve installation guidance * Formatting fix * Update docs/install/README.md link fix Co-authored-by: Evan Anderson <[email protected]> * Update docs/install/README.md link fix Co-authored-by: Evan Anderson <[email protected]> * link fix and table update More writing * Update README.md Misc edits * Update README.md Minor edits * Adding install-kn to PR Consolidating CLI installations into this this topic. * Update install-kn.md Changing red bug alert to important The old syntax was: ??? bug "Having issues upgrading `kn` to Homebrew?" * Update install-kn (snippet) Removed alert formatting * Added quickstart-install.md Various edits * Fixes and reviewed edits Made Evan suggestions, table column test, spelling fixes * Update quickstart-install.md link fix * Update README.md Replaced the table with a bulleted list approach. * Update README.md Put back the table * Added serving and eventing install topics Updated topics per effort - consolidating guidance * Link fixes * Made Evan's edits * Various updates All files added for this PR. * Link fix * Formatting fixes * Formatting and consistency fix * Update docs/install/operator/knative-with-operator-cli.md Co-authored-by: Evan Anderson <[email protected]> * Update docs/client/install-kn.md Co-authored-by: Evan Anderson <[email protected]> --------- Co-authored-by: Evan Anderson <[email protected]> * Fix edit page links, move technical docs under sub-heading (#6398) * Fix edit links by moving docs content under a dedicated subdirectory * Fix edit links by moving docs content under a dedicated subdirectory * Add High availability documentation section for eventing (#6401) I have copy-pasted from the Knative Serving documentation page the block as I found it missing when configuring it. * Update proc-running-function.md (#6400) Undo separeate kn func output for invoke * Add a note that Apache Kafka is required to use EKB (#6404) * Move install docs to administration (#6403) * Fix trailing newline complaints * Fix redirects from #6398 --------- Co-authored-by: Bruce Hamilton <[email protected]> Co-authored-by: Alexander-Kita <[email protected]> Co-authored-by: Dave Protasowski <[email protected]> Co-authored-by: Aurélien Joga <[email protected]> Co-authored-by: Christoph Stäbler <[email protected]>

Attempt to rebuild docs build process

b3b21ef

knative-prow-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 12, 2025

knative-prow bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Sep 12, 2025

knative-prow bot requested a review from pierDipi September 12, 2025 22:05

knative-prow bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Sep 12, 2025

knative-prow bot requested a review from skonto September 12, 2025 22:05

Merge remote-tracking branch 'upstream/main' into docs-rebuild

befe9af

knative-prow-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 12, 2025

Use a more modern python version

d130213

evankanderson commented Sep 12, 2025

View reviewed changes

knative-prow bot assigned dprotaso Sep 13, 2025

knative-prow bot added do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. lgtm Indicates that a PR is ready to be merged. labels Sep 13, 2025

knative-prow-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 15, 2025

Merge remote-tracking branch 'upstream/main' into docs-rebuild

57ef99a

knative-prow bot removed the lgtm Indicates that a PR is ready to be merged. label Sep 15, 2025

knative-prow-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 15, 2025

Fix strict verify, hide versions on unversioned pages

1f149a5

evankanderson force-pushed the docs-rebuild branch from 3ba9093 to 1f149a5 Compare September 15, 2025 20:37

knative-prow bot added lgtm Indicates that a PR is ready to be merged. and removed do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels Sep 15, 2025

knative-prow bot merged commit 4166fde into knative:main Sep 15, 2025
19 checks passed

This was referenced Sep 15, 2025

feat: route knative docs base URL from knative.dev/docs to knative.dev #6319

Closed

Fix edit page links, move technical docs under sub-heading #6398

Merged

Separate technical documentation from the project page #6302

Closed

evankanderson mentioned this pull request Sep 25, 2025

Cherry pick about 13 PRs into release-1.19 #6405

Merged

Attempt to rebuild docs build process, inspired by #6319 #6371

Attempt to rebuild docs build process, inspired by #6319 #6371

Uh oh!

Conversation

evankanderson commented Sep 12, 2025

Proposed Changes

Uh oh!

netlify bot commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for knative ready!

Uh oh!

evankanderson commented Sep 12, 2025

Uh oh!

evankanderson commented Sep 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dprotaso commented Sep 13, 2025

Uh oh!

evankanderson commented Sep 15, 2025

Uh oh!

evankanderson commented Sep 15, 2025

Uh oh!

dprotaso commented Sep 15, 2025

Uh oh!

knative-prow bot commented Sep 15, 2025

Uh oh!

Uh oh!

Uh oh!

netlify bot commented Sep 12, 2025 •

edited

Loading