Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+21 −27
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c4d3cea
feat: route knative docs base URL from knative.dev/docs to knative.dev
rohan-019 Aug 7, 2025
2c79dca
Fix base URL change
rohan-019 Aug 17, 2025
442aae5
Merge branch 'main' into blackboxai/route-base-url-to-knative-dev
rohan-019 Aug 23, 2025
1cc1ca0
Merge branch 'knative:main' into blackboxai/route-base-url-to-knative…
rohan-019 Aug 28, 2025
e70ff3f
Merge branch 'knative:main' into blackboxai/route-base-url-to-knative…
rohan-019 Sep 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion blog/mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ plugins:
copyright: "Copyright © 2024 The Knative Authors"

extra:
homepage: https://knative.dev/docs
homepage: https://knative.dev
# social:
# - icon: fontawesome/brands/twitter
# link: https://twitter.com/KnativeProject
Expand Down
30 changes: 6 additions & 24 deletions hack/build.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ set -x
# 1) Make a release-NN branch as normal.
# 2) Update VERSIONS below (on main) to include the new version, and remove the oldest
# Order matters :-), Most recent first.
VERSIONS=("1.18" "1.17") # Docs version, results in the url e.g. knative.dev/docs-1.9/..
VERSIONS=("1.19" "1.18" "1.17") # Docs version, results in the url e.g. knative.dev/v1.9-docs/..
# 4) PR the result to main.
# 5) Party.

Expand All @@ -41,16 +41,16 @@ readonly SITE=$PWD/site
rm -rf site/

if [ "$BUILD_VERSIONS" == "no" ]; then
# HEAD to /docs if we're not doing versioning.
mkdocs build -f mkdocs.yml -d site/docs
# HEAD to root if we're not doing versioning.
mkdocs build -f mkdocs.yml -d site
else
# Versioning: pre-release (HEAD): docs => development/
cp -r . $TEMP/docs-main
curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/main/docs/serving-api.md -s > "$TEMP/docs-main/docs/serving/reference/serving-api.md"
curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/main/docs/eventing-api.md -s > "$TEMP/docs-main/docs/eventing/reference/eventing-api.md"
pushd "$TEMP/docs-main"; mkdocs build -f mkdocs.yml -d $SITE/development; popd

# Latest release branch to /docs
# Latest release branch to root
git clone --depth 1 -b ${DOCS_BRANCHES[0]} https://github.com/${GIT_SLUG} "$TEMP/docs-$latest"

if [ ${latest#*1.} -gt 6 ]; then
Expand All @@ -61,7 +61,7 @@ else
curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/${DOCS_BRANCHES[0]}/docs/eventing-api.md -s > "$TEMP/docs-$latest/docs/reference/api/eventing-api.md"
fi

pushd "$TEMP/docs-$latest"; KNATIVE_VERSION="${VERSIONS[0]}.0" SAMPLES_BRANCH="${DOCS_BRANCHES[0]}" mkdocs build -d $SITE/docs; popd
pushd "$TEMP/docs-$latest"; KNATIVE_VERSION="${VERSIONS[0]}.0" SAMPLES_BRANCH="${DOCS_BRANCHES[0]}" mkdocs build -d $SITE; popd
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this do for the v1.18 docs (for example)?

It feels like we want to host the /docs/index.html up to /index.html, but maybe leave the other content (except the blog) under /docs. I'm concerned mostly about the nav getting screwed up, but also it seems like the home page (and blog and community info) might actually be a different type of content than the versioned documentation.

Sorry to get this feedback to you late; I hadn't really looked at the current implementation until you sent this PR.

I'm willing to try moving forward with this and seeing what goes wrong, with the understanding that we might revert this change as the first fix if there are problems, and then later attempt a more complete fix.

Copy link
Author

@rohan-019 rohan-019 Aug 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@evankanderson Thank you for the thorough review and constructive feedback - I appreciate you taking the time to examine the implementation details.
This change affects how the latest documentation (v1.19) is served:

What happens to v1.18 docs: Nothing changes - they remain at knative.dev/v1.18-docs/

What changes: Only the latest/current docs move from knative.dev/docs/ to knative.dev/ (root)

Your navigation concern is valid - this creates inconsistent URL patterns:

  • Latest docs: Root-level (knative.dev/)
  • Versioned docs: Subdirectory (knative.dev/v1.18-docs/)
  • Blog navigation: Still references /docs/ paths (needs fixing)

Potential issues:

  1. Cross-version navigation links may break
  2. Blog → main site links will break (11 hardcoded /docs/ references in blog/config/nav.yml)
  3. Version switcher functionality needs testing

Mitigation: The 301 redirects handle SEO concerns, but we should:

  1. Fix blog navigation references immediately
  2. Test version switcher thoroughly
  3. Monitor for broken cross-references
  4. Have rollback plan ready

I agree with proceeding cautiously - the redirect strategy is solid for SEO, but navigation UX needs careful validation.

Immediate next steps:

  1. Fix blog navigation /docs/ references
  2. Test version switcher thoroughly
  3. Monitor cross-version link behavior
  4. Keep rollback plan ready

Let me know how you want to approach testing the new URL paths - I'm not sure how moving all the docs to the root will affect things like the nav.

Thanks for being willing to move forward thoughtfully - your "try and see what breaks" approach with proper safeguards is exactly right for this type of infrastructure change.


# Previous release branches release-$version to /v$version-docs
versionjson=""
Expand Down Expand Up @@ -107,25 +107,7 @@ cp golang/*.html site/golang/
cat golang/_redirects >> site/_redirects


# Home page is served from docs, so add a redirect.
cat << EOF > site/index.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Redirecting</title>
<noscript>
<meta http-equiv="refresh" content="1; url=docs/" />
</noscript>
<script>
window.location.replace("docs/");
</script>
</head>
<body>
Redirecting to <a href="docs/">docs/</a>...
</body>
</html>
EOF
# Home page is now served directly from root, no redirect needed

# Clean up
rm -rf $TEMP
Expand Down
4 changes: 2 additions & 2 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
INHERIT: config/nav.yml

site_name: Knative
site_url: https://knative.dev/docs
site_url: https://knative.dev
site_description: Knative Documentation
extra_css:
- stylesheets/extra.css

repo_url: https://github.com/knative/docs
edit_uri: edit/main/docs
edit_uri: edit/main

theme:
name: material
Expand Down
12 changes: 12 additions & 0 deletions netlify.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,15 @@
from = "/docs/help/contributor/*"
to = "https://github.com/knative/docs/blob/main/contribute-to-docs/README.md"
status = 301

# Redirect from /docs/* to root to handle the base URL change
[[redirects]]
from = "/docs/*"
to = "/:splat"
status = 301

# Redirect old /docs path to root
[[redirects]]
from = "/docs"
to = "/"
status = 301