Skip to content

Migrate documentation from MkDocs to Docsy#4734

Open
iromanycheva-eng wants to merge 4 commits intokubernetes-sigs:mainfrom
iromanycheva-eng:migrate-to-docsy
Open

Migrate documentation from MkDocs to Docsy#4734
iromanycheva-eng wants to merge 4 commits intokubernetes-sigs:mainfrom
iromanycheva-eng:migrate-to-docsy

Conversation

@iromanycheva-eng
Copy link
Copy Markdown
Contributor

@iromanycheva-eng iromanycheva-eng commented Apr 7, 2026 •
edited
Loading

What type of PR is this?
/kind documentation

Optionally add one or more of the following kinds if applicable:

What this PR does / why we need it:

We need to migrate documentation from MkDocs to Docsy because there is a better support for google analytics. Besides Docsy is a recommended theme for kubernetes sites.

Which issue(s) this PR fixes:

Fixes #4729

Does this PR introduce a user-facing change?:

Migrate documentation from MkDocs to Docsy

@k8s-ci-robot
Copy link
Copy Markdown
Contributor

k8s-ci-robot commented Apr 7, 2026

Adding the "do-not-merge/release-note-label-needed" label because no release-note block was detected, please follow our release note process to remove it.

Details

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.

@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels Apr 7, 2026
@k8s-ci-robot k8s-ci-robot added the kind/gep PRs related to Gateway Enhancement Proposal(GEP) label Apr 7, 2026
@k8s-ci-robot
Copy link
Copy Markdown
Contributor

k8s-ci-robot commented Apr 7, 2026

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: iromanycheva-eng
Once this PR has been reviewed and has the lgtm label, please assign thockin for approval. For more information see the Code Review Process.

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

Details Needs approval from an approver in each of these files:

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

@k8s-ci-robot k8s-ci-robot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Apr 7, 2026
@k8s-ci-robot
Copy link
Copy Markdown
Contributor

k8s-ci-robot commented Apr 7, 2026

Hi @iromanycheva-eng. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

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.

@k8s-ci-robot k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Apr 7, 2026
@iromanycheva-eng iromanycheva-eng force-pushed the migrate-to-docsy branch 2 times, most recently from f40ad5c to 5e1c8a3 Compare April 7, 2026 06:41
@iromanycheva-eng iromanycheva-eng marked this pull request as ready for review April 7, 2026 22:56
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Apr 7, 2026
@k8s-ci-robot k8s-ci-robot requested review from candita and robscott April 7, 2026 22:56
@bexxmodd
Copy link
Copy Markdown
Contributor

bexxmodd commented Apr 8, 2026

Looks like all moved or renamed files are added as new in this PR. Can we mark them as moved instead?

@k8s-ci-robot k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 10, 2026
@k8s-ci-robot k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 10, 2026
@youngnick
Copy link
Copy Markdown
Contributor

youngnick commented Apr 13, 2026

This looks really great!

A couple of things that I think could be better though:

The Overview style pages would ideally be the landing page for each of the headings, as they are today, rather than the table of contents that they are in the current state.

So:

  • the Overview subtree would have the Introduction page be the landing page
  • the Guides section would have the Getting Started/Introduction page be the landing page
  • the Enhancements section would have the Overview page be the landing page
  • the Contributing section would have the How to get Involved page be the landing page

When navigating GEPs, the table of contents on the left disappears when you get down to the actual GEP itself. Ideally this would at least show the parent, or auto-expand the current section or something.

Aside from that, I think this is looking pretty close. Shockingly so, well done.

@youngnick
Copy link
Copy Markdown
Contributor

youngnick commented Apr 13, 2026

/ok-to-test

@k8s-ci-robot k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Apr 13, 2026
@k8s-ci-robot k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 15, 2026
jgreeer
jgreeer reviewed Apr 15, 2026
View reviewed changes
Comment thread site/content/en/reference/api-types/policy/backendtlspolicy.md Outdated
jgreeer
jgreeer reviewed Apr 15, 2026
View reviewed changes
Comment thread site/content/en/reference/api-types/policy/backendtlspolicy.md Outdated
jgreeer
jgreeer reviewed Apr 15, 2026
View reviewed changes
Comment thread site/content/en/guides/user-guides/tls.md Outdated
jgreeer
jgreeer reviewed Apr 15, 2026
View reviewed changes
Comment thread site/content/en/reference/policy-attachment.md Outdated
jgreeer
jgreeer reviewed Apr 15, 2026
View reviewed changes
Comment thread site/content/en/docs/concepts/versioning.md
jgreeer
jgreeer reviewed Apr 15, 2026
View reviewed changes
Comment thread site/hugo.toml Outdated
@k8s-ci-robot k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 16, 2026
@iromanycheva-eng iromanycheva-eng force-pushed the migrate-to-docsy branch 2 times, most recently from 27d825e to cdbe928 Compare April 17, 2026 04:46
@k8s-ci-robot k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 17, 2026
@youngnick
Copy link
Copy Markdown
Contributor

youngnick commented Apr 17, 2026

This is looking LGTM to me, but I think it may need to wait until after next Friday, when I merge the Implementations Page review for v1.5. I think that's the only docs PR we have in flight, but I can't merge that earlier for process fairness reasons.

@youngnick
Copy link
Copy Markdown
Contributor

youngnick commented Apr 17, 2026

/hold

@rikatz
Copy link
Copy Markdown
Member

rikatz commented Apr 17, 2026

@youngnick can we hold until next week? I still need to finalize the python script for redirect :D I will try my best to do it today or early next week!

Thanks!

rikatz
rikatz reviewed Apr 17, 2026
View reviewed changes
Comment thread Makefile Outdated
docker build --pull -t gaie/mkdocs hack/mkdocs/image
docker rm -f $(DOCS_BUILD_CONTAINER_NAME) || true
docker run --name $(DOCS_BUILD_CONTAINER_NAME) --rm -v ${PWD}:/docs gaie/mkdocs build
docker run --rm -v ${PWD}:/src -w /src/site peaceiris/hugo:v0.148.0-extended hugo
Copy link
Copy Markdown
Member

@rikatz rikatz Apr 17, 2026

Choose a reason for hiding this comment

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

maybe make this version configurable somewhere or a flag on the Makefile

rikatz
rikatz reviewed Apr 17, 2026
View reviewed changes
Comment thread site/hugo.toml Outdated
rikatz
rikatz reviewed Apr 17, 2026
View reviewed changes
Comment thread site/content/en/guides/getting-started/migrating-from-ingress.md

```yaml
{% include 'standard/simple-http-https/gateway.yaml' %}
apiVersion: gateway.networking.k8s.io/v1
Copy link
Copy Markdown
Member

@rikatz rikatz Apr 17, 2026

Choose a reason for hiding this comment

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

can't we have this include on docsy anymore? I think that on Kubernetes docs they do it, maybe it is worth using the same or similar approach

Copy link
Copy Markdown
Contributor Author

@iromanycheva-eng iromanycheva-eng Apr 18, 2026

Choose a reason for hiding this comment

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

I'll try to find the solution and create a separate commit for it.

@k8s-ci-robot k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 17, 2026
@iromanycheva-eng
Migrate documentation from MkDocs to Docsy with full rename tracking
0762008
@iromanycheva-eng
Modify landing page navigation flow
0738036 
Redirect section headers to the first subtree content page instead of the TOC. Include breadcrumbs in Geps to enhance user navigation.
@iromanycheva-eng
Fix broken links
8783cb9 
Also upgrade version of hugo and docsy
@iromanycheva-eng
Switch back from /enhancements to /geps
8aa304a
@k8s-ci-robot k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rikatz rikatz rikatz left review comments

@davidjumani davidjumani Awaiting requested review from davidjumani

@candita candita Awaiting requested review from candita

@robscott robscott Awaiting requested review from robscott

+1 more reviewer

@jgreeer jgreeer jgreeer left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. kind/gep PRs related to Gateway Enhancement Proposal(GEP) ok-to-test Indicates a non-member PR verified by an org member that is safe to test. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Migrate our documentation from MkDocs to Docsy

6 participants

@iromanycheva-eng @k8s-ci-robot @bexxmodd @youngnick @rikatz @jgreeer