feat: route knative docs base URL from knative.dev/docs to knative.dev #6319
Conversation
- Updated base URL configuration from knative.dev/docs to knative.dev - Added comprehensive 301 redirects for smooth transition - Updated blog configuration to point to new base URL - Ensures backward compatibility with existing links and search results This change routes the base URL for Knative docs to knative.dev instead of knative.dev/docs, while maintaining backward compatibility through proper redirects that won't break search results or existing links.
✅ Deploy Preview for knative ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Welcome @rohan-019! It looks like this is your first PR to knative/docs 🎉 |
knative-prow
bot
added
the
size/S
|
/ok-to-test |
knative-prow
bot
added
the
ok-to-test
|
Hey, @rohan-019 ! Thanks for doing this. In the preview, I'm not seeing the described effect, though I can see that you made changes intended to produce this effect. Am I looking at something wrong? E.g. (and yes, serving HTML for a 301 is not great...) |
|
Hi @evankanderson, Thanks for checking! It looks like the root is still serving a redirect to /docs/, which means the Netlify build output path is probably still pointing at /docs. I’ll update the Netlify publish directory (or verify the MkDocs build path) so the docs are served directly at /. The 301 redirect from /docs/* → / will stay in place so existing links and crawlers are preserved. |
knative-prow
bot
added
size/M
knative-prow-robot
added
the
needs-rebase
knative-prow-robot
removed
the
needs-rebase
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: evankanderson, rohan-019 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:
Approvers can indicate their approval by writing |
knative-prow
bot
added
the
approved
No problem at all, and sorry for my late response too. Thanks for reviewing—I’ll check it now. |
|
cc: @evankanderson |
|
I've cloned your changes locally, and run the following commands (on Linux, sorry!) to get a build working and browsable: Unfortunately, the top-nav seems busted for the v1.19 version, and a lot of the meta-data (such as the canonical link in (Also, it looks like you haven't signed the LF CLA, so you'll need to do that before this can get merged.) |
|
I think (based on #6502), we may want the following URL structure:
I think that should minimize the amount of redirects / broken links that need to be adjusted, while moving all the non-technical documentation out of the versioned section. I don't know if we want to implement this as adding another layer |
rohan-019
force-pushed
the
blackboxai/route-base-url-to-knative-dev
branch
from
13ec24f to
1cc1ca0
Compare
Signed-off-by: rohan-019 <[email protected]>
knative-prow
bot
added
size/L
There was a problem hiding this comment.
I'm sorry that this is proving so gnarly!
I've tried poking a bit at your configuration, and I'm also having trouble figuring out the best path. So far, what I think might work:
- Keep the
build.shscript mostly the same. - Copy the
docs/index.htmlfromsiteup to the root level after the build, instead of creating thesite/index.htmldirectly. - You might consider doing the same treatment for
aboutandcommunity, and fixing the links inoverrides/partials/header.html, but that might be too much.
Sorry to have had a hidden minefield in here -- I'm guessing that's part of why it wasn't fixed previously!
Thanks a lot for the back-to-back responses. I’ll review and make the updates, then get back to you shortly. |
- Restore version JSON block for version picker functionality - Stop copying /about and /community into versioned builds - Restore API reference curl fetches for serving-api.md and eventing-api.md - Restore /development build step - Copy index.html and sitemap.xml to root after build - Update navigation to point to correct paths (root vs versioned) - Fix top-nav links to use proper URL structure
Home.-.Knative.-.Google.Chrome.2025-09-06.11-45-22.mp4What doesn't: Docs and Blog pages show "files not found" |
| @@ -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/.. | |||
There was a problem hiding this comment.
We're not quite ready to release 1.19 -- the OpenTelemetry changes came in late and we've had to push some bug fixes.
| # Create docs directory structure | ||
| mkdir -p "$SITE/docs" | ||
|
|
||
| # Build latest docs to /docs |
There was a problem hiding this comment.
We were building the next-release docs to /development/... and the most-recent-release docs to /docs/.... I think you've changed this to build the next-release docs to /docs/..., and not publish docs for the current release anywhere.
| if [ "$BUILD_VERSIONS" == "no" ]; then | ||
| # HEAD to /docs if we're not doing versioning. | ||
| mkdocs build -f mkdocs.yml -d site/docs | ||
| # Build to root if we're not doing versioning | ||
| mkdocs build -f mkdocs.yml -d site |
There was a problem hiding this comment.
FWIW, this "tiny build for preview" seems to potentially be the part that's messing things up. I wonder if we want to remove it for now, and leave a TODO to optimize this later. (The preview version is also not importing the serving/eventing reference docs, and makes it hard to reason about these sorts of changes from the preview.)
| # Build development site | ||
| pushd "$TEMP/docs-main" | ||
| KNATIVE_VERSION="${VERSIONS[0]}.0" SAMPLES_BRANCH="${DOCS_BRANCHES[0]}" mkdocs build -f mkdocs.yml -d "$SITE/development" | ||
| popd |
There was a problem hiding this comment.
Why are we repeating 56-58 here?
| # Move non-versioned content to root level | ||
| mkdir -p "$SITE/about" | ||
| cp -r "$TEMP/docs-main/docs/about" "$SITE/" | ||
| mkdir -p "$SITE/community" | ||
| cp -r "$TEMP/docs-main/docs/community" "$SITE/" |
There was a problem hiding this comment.
I think this may break links for images, CSS, and JavaScript for these pages. I'll attempt another build with your changes this afternoon (I avoided this PR yesterday because I had a few other items and I really got pulled in on Friday).
There was a problem hiding this comment.
The index.html did seem to mostly work with just a copy, mostly because that page is largely hand-crafted HTML.
There are still a few items I'm trying to figure out in the navigation -- like why the "blog", "about", and "community" links don't show up in the navigation tabs, despite being in nav.html.
| # Create version JSON for version picker | ||
| versionjson="" | ||
| for i in "${!previous[@]}"; do | ||
| version=${previous[$i]} | ||
| versionjson+="{\"version\": \"v$version-docs\", \"title\": \"v$version\", \"aliases\": [\"\"]}," |
There was a problem hiding this comment.
This was previously in the loop on 60-74. I don't have a strong opinion, but it feels slightly odd to have the same loop twice with some other actions in between.
Thanks for the detailed feedback, @evankanderson I’ve noted the possible follow-ups from your review: Once you confirm whether the current changes work, I’ll be ready to address any of these (either here or in a follow-up PR as appropriate). |
|
Building the multi-version site and then moving |
|
I think I might have a solution, but it's a bit more invasive. Frankly, this never worked quite right to begin with (witness the homepage redirecting to |
What Happened 🔍 |
|
If you already have a more invasive fix in mind, I’m happy to wait for your direction and adjust this PR (or follow up in a new one) once the bigger change is in place. |
|
I have a partial fix that involves moving the documentation into a sub-directory, and doing one https://github.com/knative/docs/compare/main...evankanderson:docs:docs-rebuild?expand=1 (Ignore the blog changes, I think I screwed up something when committing things quickly.) I don't have things entirely fixed, but the changes to the nav partial seem to get the secondary bar nav working again: 
I need to get the sidebar nav to cut out one more level, which probably means overriding more partials, and adding some documentation about why we're doing what we're doing. |
|
(But I need to get out and run right now -- more updates later tonight, or feel free to ask questions / take my changes and run with them) |
|
Thanks for digging into this, @evankanderson Happy to either wait for your next update or pick up from your branch if that helps move things forward faster. |
|
Feel free to pull in changes from my branch, and I can add some PRs to your branch as well if you want. A few things from my branch:
|
knative-prow-robot
added
the
needs-rebase
|
PR needs rebase. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
You probably saw, but #6371 merged, which I think includes this functionality. Thanks for starting on this, and highlighting a lot of the challenges. Your work probably saved me a couple days of trying things before I ended up with that PR (which is pretty big). There are still a number of additional cleanup items from that if you're interested:
Thanks again for getting this work started! I think the end result is an improvement, and I really viewed this as a team effort -- I wouldn't have done it without you. |
|
Hi @evankanderson, very sorry for the late reply — I got caught up with some other work last week. Really glad to see #6371 merged 🎉 It’s great that our back-and-forth and experiments led to that outcome. Thanks for building on the initial work I started and pushing it through — the end result looks like a big improvement. I appreciate the detailed notes on the follow-up cleanup tasks. I’d be happy to start looking into some of the smaller items, like directory moves or link consistency. I’ll also take a look at the CNCF Tech Doc Recommendations umbrella issue (#6301) to see where else I can contribute. Thanks again for treating this as a team effort — I learned a lot through this process and really enjoyed collaborating on it! |
Migrate documentation from /docs/* to root domain with 301 redirects
Overview
This PR restructures the Knative documentation URL hierarchy by moving content from
https://knative.dev/docs/*tohttps://knative.dev/*, creating a cleaner and more intuitive navigation experience.fixes: #6292
Changes Made
Configuration Updates
site_urlfromhttps://knative.dev/docstohttps://knative.devRedirect Strategy
Benefits
Testing Completed
/docs/*→/*redirects function correctlyImpact
/docs/*URLs remain functional via redirects