Skip to content

Migrate documentation from MkDocs to Docsy - #4734

Merged
k8s-ci-robot merged 10 commits into
kubernetes-sigs:mainfrom
iromanycheva-eng:migrate-to-docsy
May 14, 2026
Merged

k8s-ci-robot merged 10 commits into
kubernetes-sigs:mainfrom
iromanycheva-eng:migrate-to-docsy

Conversation

@iromanycheva-eng

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

Copy link
Copy Markdown
Contributor

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 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 kind/gep PRs related to Gateway Enhancement Proposal(GEP) 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

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

bexxmodd commented Apr 8, 2026

Copy link
Copy Markdown
Contributor

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

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

/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
@iromanycheva-eng
iromanycheva-eng force-pushed the migrate-to-docsy branch 2 times, most recently from e3facf6 to e55be90 Compare April 15, 2026 06:53
@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
Comment thread site/go.mod Resolved
Comment thread site/hugo.toml
id = "G-JPP6RFM2BP"

# Allow Hugo to download fonts via resources.GetRemote
[security]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

is this really necessary? I can't see this same directive on https://github.com/kubernetes/website/blob/main/hugo.toml

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

are you asking about gtag or security ? If gtag, yes, it is. That's how we track gw website metrics.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

security, specifically Hugo to Download fonts:

  [security.http]
    mediaTypes = ['(?i)^font/.*$', '(?i)^application/font-woff$']

Comment thread site/hugo.toml Resolved
Comment thread Makefile Resolved
@rikatz

rikatz commented May 12, 2026

Copy link
Copy Markdown
Member

@iromanycheva-eng first of all, thanks for the whole work here!! This is great!

Some findings:

  • The API reference is generating the tags of <excludeFromCRD> weirdly, look at https://deploy-preview-4734--kubernetes-sigs-gateway-api.netlify.app/reference/api-spec/main/spec/#absoluteuri
  • I would prefer to remove the right bar from APIReference if possible. Or better, if docsy supported a button to extend/reduce it (this can be a followup!)
  • The code snippets are not respecting the dark mode theme (this can be a followup, I've found on another project that this is an issue with Docsy!)
  • I don't "love" the fact we need weights now on every frontmatter definition, but I think we can solve it later :D

Not now, but eventually we can update docsy to 0.15 and get https://www.docsy.dev/blog/2026/0.15.0/#doc-rooted-sites for free :D (and maybe we can start considering a versioned docs per release as well)

@k8s-ci-robot k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label May 13, 2026
@iromanycheva-eng
iromanycheva-eng force-pushed the migrate-to-docsy branch 2 times, most recently from 79ce654 to 4b71aaf Compare May 13, 2026 02:17
@iromanycheva-eng

Copy link
Copy Markdown
Contributor Author

@iromanycheva-eng first of all, thanks for the whole work here!! This is great!

Some findings:

  • The API reference is generating the tags of <excludeFromCRD> weirdly, look at https://deploy-preview-4734--kubernetes-sigs-gateway-api.netlify.app/reference/api-spec/main/spec/#absoluteuri
  • I would prefer to remove the right bar from APIReference if possible. Or better, if docsy supported a button to extend/reduce it (this can be a followup!)
  • The code snippets are not respecting the dark mode theme (this can be a followup, I've found on another project that this is an issue with Docsy!)
  • I don't "love" the fact we need weights now on every frontmatter definition, but I think we can solve it later :D

Not now, but eventually we can update docsy to 0.15 and get https://www.docsy.dev/blog/2026/0.15.0/#doc-rooted-sites for free :D (and maybe we can start considering a versioned docs per release as well)

@rikatz , thank you for all the comments. Really appreciate such a thorough review.

  1. - fixed.
  2. I made the right bar collapsed by default.
  3. The code snippets are fixed.

Comment thread apisx/v1alpha1/xlistenerset_types.go Resolved
Redirect section headers to the first subtree content page instead of the TOC. Include breadcrumbs in Geps to enhance user navigation.
Also upgrade version of hugo and docsy
Fix some rendering and icons
Delete the github references. Fix some rendering and scripts.
Add go and npm dependencies to the dependabot. Refactor geps pages parsing.
Makefile: Use Docker for Hugo
CI: Install Hugo manually instead of using a 3rd party action
UI: Support dark mode for code blocks and make TOC collapsible
Generator: Strip excludeFromCRD tags from generated spec files.
@rikatz

rikatz commented May 14, 2026

Copy link
Copy Markdown
Member

/lgtm
/approve

Thanks @iromanycheva-eng !

@bexxmodd as a followup we need to incorporate https://github.com/kubernetes-sigs/gateway-api/pull/4848/changes again

@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: iromanycheva-eng, rikatz, youngnick

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

The pull request process is described 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

@rikatz

rikatz commented May 14, 2026

Copy link
Copy Markdown
Member

/hold cancel

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/gep PRs related to Gateway Enhancement Proposal(GEP) lgtm "Looks good to me", indicates that a PR is ready to be merged. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. release-note Denotes a PR that will be considered when it comes time to generate release notes. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Migrate our documentation from MkDocs to Docsy

7 participants