Fix strict verify, hide versions on unversioned pages

evankanderson · evankanderson · commit 3ba90934dc38 · 2025-09-15T13:35:21.000-07:00
diff --git a/.github/workflows/mkdocs-strict-verify.yaml b/.github/workflows/mkdocs-strict-verify.yaml
@@ -25,12 +25,8 @@ jobs:
 
   verify:
     name: Verify mkdocs strict
-    strategy:
-      matrix:
-        go-version: [1.16.x]
-        platform: [ubuntu-latest]
 
-    runs-on: ${{ matrix.platform }}
+    runs-on: ubuntu-latest
 
     env:
       GOPATH: ${{ github.workspace }}
@@ -47,4 +43,4 @@ jobs:
       run: python3 -m pip install -r requirements.txt
 
     - name: Verify MkDocs
-      run: mkdocs build --strict
+      run: ./hack/build.sh strict
diff --git a/config/redirects.yml b/config/redirects.yml
@@ -82,7 +82,7 @@ plugins:
       docs/community/contributing/steering-committee.md: https://github.com/knative/community/blob/main/STEERING-COMMITTEE.md
       docs/community/contributing/tech-oversight-committee.md: https://github.com/knative/community/blob/main/TECH-OVERSIGHT-COMMITTEE.md
       docs/community/contributing/trademark-committee.md: https://github.com/knative/community/blob/main/TRADEMARK-COMMITTEE.md
-      docs/community/contributing/values.md: docs/https://github.com/knative/community/blob/main/VALUES.md
+      docs/community/contributing/values.md: https://github.com/knative/community/blob/main/VALUES.md
       docs/community/contributing/working-groups/working-groups.md: https://github.com/knative/community/blob/main/working-groups
       docs/community/meetup.md: community/README.md
       docs/community/samples.md: https://github.com/knative/docs/tree/main/code-samples/community
@@ -147,7 +147,7 @@ plugins:
       docs/eventing/samples/helloworld/helloworld-python/README.md: https://github.com/knative/docs/tree/main/code-samples/eventing/helloworld/helloworld-python
       docs/eventing/samples/kafka/binding/README.md: https://github.com/knative/docs/tree/main/code-samples/eventing/kafka/binding
       docs/eventing/samples/kafka/channel/README.md: https://github.com/knative/docs/tree/main/code-samples/eventing/kafka/channel
-      docs/eventing/samples/kubernetes-event-source/index.md: eventing/sources/apiserversource/README.md
+      docs/eventing/samples/kubernetes-event-source/index.md: docs/eventing/sources/apiserversource/README.md
       docs/eventing/samples/parallel/README.md: https://github.com/knative/docs/tree/main/code-samples/eventing/parallel
       docs/eventing/samples/parallel/multiple-branches/README.md: https://github.com/knative/docs/tree/main/code-samples/eventing/parallel/multiple-branches
       docs/eventing/samples/parallel/mutual-exclusivity/README.md: https://github.com/knative/docs/tree/main/code-samples/eventing/parallel/mutual-exclusivity
@@ -207,7 +207,7 @@ plugins:
       docs/serving/samples/hello-world/helloworld-nodejs/README.md: https://github.com/knative/docs/tree/main/code-samples/serving/hello-world/helloworld-nodejs
       docs/serving/samples/hello-world/helloworld-php/README.md: https://github.com/knative/docs/tree/main/code-samples/serving/hello-world/helloworld-php
       docs/serving/samples/hello-world/helloworld-python/README.md: https://github.com/knative/docs/tree/main/code-samples/serving/hello-world/helloworld-python
-      docs/serving/samples/hello-world/helloworld-ruby/README.md: docs/https://github.com/knative/docs/tree/main/code-samples/serving/hello-world/helloworld-ruby
+      docs/serving/samples/hello-world/helloworld-ruby/README.md: https://github.com/knative/docs/tree/main/code-samples/serving/hello-world/helloworld-ruby
       docs/serving/samples/hello-world/helloworld-scala/README.md: https://github.com/knative/docs/tree/main/code-samples/serving/hello-world/helloworld-scala
       docs/serving/samples/hello-world/helloworld-shell/README.md: https://github.com/knative/docs/tree/main/code-samples/serving/hello-world/helloworld-shell
       docs/serving/samples/knative-routing-go/README.md: https://github.com/knative/docs/tree/main/code-samples/serving/knative-routing-go
diff --git a/docs/blog/articles/get-started-knative-eventing.md b/docs/blog/articles/get-started-knative-eventing.md
@@ -5,7 +5,10 @@
 I’ve been exploring [Knative Eventing](https://knative.dev/docs/eventing/), a system that enables a cloud native eventing ecosystem to be easily deployed through the use of **event producers** and **event consumers.** Most of the work on this demo has been done in version 0.11, and I have also run it in version 0.13, and now it also works on version 0.15.
 
 This demo was presented at the first Knative Community Meetup, so you can also watch the video version here:
-{{< youtube sGi_LuAaaT0 >}}
+
+<div class="video-wrapper">
+  <iframe width="720" height="480" src="https://www.youtube.com/embed/sGi_LuAaaT0" frameborder="0" allowfullscreen></iframe>
+</div>
 
 I put together a simple demo to explore some of the key advantages of event-driven architectures, such as:
 
diff --git a/docs/blog/articles/orchestrating-cloud-events-with.md b/docs/blog/articles/orchestrating-cloud-events-with.md
@@ -184,7 +184,11 @@ As mentioned before, further integrations should deal with more advanced topolog
 
 In this blog post, I’ve spent some time describing the wonders of what you can do with a Workflow Engine like Zeebe on top of Knative Applications. I’ve personally had a lot of fun while working with Knative, as the abstractions provided helped me to build a very robust application that I can move to different cloud providers easily, without changing any of my services.
 Watch this demo live here:
-{{< youtube msDDdqmyEFA >}}
+
+<div class="video-wrapper">
+  <iframe width="720" height="480" src="https://www.youtube.com/embed/msDDdqmyEFA" frameborder="0" allowfullscreen></iframe>
+</div>
+
 The projects and the integration shown in this blog post are in active development, so if you are interested or want to get involved please reach out via twitter: [@salaboy](http://twitter.com/salaboy) or join our slack channel: [zeebe-io.slack.com](http://zeebe-io.slack.com)
 
 If you want to run this demo in your own Kubernetes Cluster you can find the instructions here: [https://github.com/salaboy/orchestrating-cloud-events/](https://github.com/salaboy/orchestrating-cloud-events/) and if you feel like giving the repository a star we will appreciate it :)
diff --git a/docs/blog/releases/announcing-knative-v0-21-release.md b/docs/blog/releases/announcing-knative-v0-21-release.md
@@ -190,7 +190,7 @@ Please refer to issue [#1144](https://github.com/knative/client/issues/1144) (an
 
 **ACTION REQUIRED**
 
-If you rely on client-side revision naming, you have to add `--revision-name {{.Service}}-{{.Random 5}}-{{.Generation}}` to `kn service create` to get back the previous default behaviour. However, in most of all cases, you shound not worry about whether the revision names are created by `kn` or by the Knative serving controller
+If you rely on client-side revision naming, you have to add `{{ '--revision-name {{.Service}}-{{.Random 5}}-{{.Generation}}' }}` to `kn service create` to get back the previous default behaviour. However, in most of all cases, you shound not worry about whether the revision names are created by `kn` or by the Knative serving controller
 
 In case of issues with this change, please let us know and we will fix it asap. We are committed to supporting you with any issues caused by this change.
 
diff --git a/docs/community/contributing.md b/docs/community/contributing.md
@@ -71,7 +71,7 @@ Submit a Pull Request to the community sample directory under the Knative compon
 - [Contribute code samples](https://github.com/knative/docs/tree/main/code-samples/community):
 Share your samples with the community.
 
-- [Link existing code samples](../samples/README.md#external-code-samples):
+- [Link existing code samples](../docs/samples/README.md#external-code-samples):
 Link to your Knative samples that live on another site.
 
 ## Contributor Roles
diff --git a/docs/smoketest.md b/docs/smoketest.md
diff --git a/hack/build.sh b/hack/build.sh
@@ -53,6 +53,8 @@ cp -r "$TEMP/content/docs/images" "$TEMP/content/docs/docs/images"
 
 # Point top-level nav to docs directory.
 echo -e "nav:\n- docs\n- about\n- blog\n- community" > "$TEMP/content/docs/.nav.yml"
+# We use samples_branch to flag that the documentation is versioned
+echo -e "\n\nsamples_branch: main" >> "$TEMP/content/docs/docs/.meta.yml"
 curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/main/docs/serving-api.md -s > "$TEMP/content/docs/docs/serving/reference/serving-api.md"
 curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/main/docs/eventing-api.md -s > "$TEMP/content/docs/docs/eventing/reference/eventing-api.md"
 versionjson="{\"version\": \"docs\", \"title\": \"(Pre-release)\", \"aliases\": [\"\"]}"
@@ -77,6 +79,8 @@ if [ "$BUILD_VERSIONS" != "no" ]; then
   if [ ! -f "$TEMP/content/docs/docs/.nav.yml" ]; then
     sed '/- Blog:/,$d' "$TEMP/current-release/config/nav.yml" >> "$TEMP/content/docs/docs/.nav.yml"
   fi
+  # Smoketests were written for Hugo, not mkdocs, so remove
+  rm "$TEMP/content/docs/docs/smoketest.md"
   # Fill in meta content for macros.py
   echo -e "\n\nknative_version: ${VERSIONS[0]}.0\nsamples_branch: ${DOCS_BRANCHES[0]}" >> "$TEMP/content/docs/docs/.meta.yml"
 
@@ -92,6 +96,8 @@ if [ "$BUILD_VERSIONS" != "no" ]; then
     cp -r "$TEMP/docs-$version/docs" "$TEMP/content/docs/v$version-docs"
     echo "- Docs: v${version}-docs" >> "$TEMP/content/docs/.nav.yml"
     echo "      v${version}-docs/README.md: v${version}-docs/concepts/README.md" >> "$TEMP/content/config/redirects.yml"
+    # Smoketests were written for Hugo, not mkdocs, so remove
+    rm "$TEMP/content/docs/v$version-docs/smoketest.md"
     # Copy the nav, but strip out non-versioned content, starting with blog
     # This can be retired after we stop supporting v1.19.
     if [ ! -f "$TEMP/content/docs/v$version-docs/.nav.yml" ]; then
@@ -108,7 +114,8 @@ fi
 
 # Only build the site _once_ -- we used to build sub-components, and it
 # introduced a bunch of navigation / base-url problems.
-(cd "$TEMP/content"; mkdocs build -f mkdocs.yml -d "$SITE")
+# We pass through the command-line arguments to this script to enable --strict checks in CI.
+(cd "$TEMP/content"; mkdocs build -f mkdocs.yml -d "$SITE" "$@")
 
 # Set up the version file to point to the set of built docs.
 cat << EOF > $SITE/versions.json
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -5,6 +5,16 @@ site_url: https://knative.dev/docs
 site_description: Knative Documentation
 extra_css:
   - stylesheets/extra.css
+# Don't try to make snippets into regular docs (e.g. link-checking, nav, etc)
+exclude_docs: |
+  *docs/snippets/
+
+# TODO: make these stricter (move to "warn" to flag new link breakages)
+# validation:
+  # omitted_files: warn
+  # absolute_links: relative_to_docs
+  # anchors: warn
+  # unrecognized_links: warn
 
 repo_url: https://github.com/knative/docs
 edit_uri: edit/main/docs
diff --git a/overrides/main.html b/overrides/main.html
@@ -31,7 +31,8 @@ <h1>⚠ You are viewing an archived snapshot of the documentation for Knative ve
   {% set _.tags = config.extra.tags %}
 
   <!-- Versioning -->
-  {%- if config.extra.version -%}
+  {# This is changed from upstream to only show version picker on versioned pages #}
+  {%- if page and (page.meta.samples_branch) -%}
     {%- set mike = config.plugins.mike -%}
     {%- if not mike or mike.config.version_selector -%}
       {%- set _.version = config.extra.version -%}
diff --git a/smoketest.md b/smoketest.md
