Migrate docsy 0.13.0

[Okabe-Junya]

Describe your changes

• Upgrade Docsy theme from v0.6.0 to v0.13.0
• Copy custom partials to layouts/_partials/ for Hugo compatibility with Docsy 0.7+
• Remove some custom partials that are now handled by Docsy defaults

Related issue number or link (ex: resolves #issue-number)

close #3609

Checklist before opening this PR (put x in the checkboxes)

• This PR does not contain plagiarism
  • don’t copy other people’s work unless you are quoting and contributing it to them.
• I have signed off on all commits
  • signing off (ex: git commit -s) is to affirm that commits comply DCO. If you are working locally, you could add an alias to your gitconfig by running git config --global alias.ci "commit -s".

[netlify]

✅ Deploy Preview for cncfglossary ready!

Name	Link
🔨 Latest commit	82f822e
🔍 Latest deploy log	https://app.netlify.com/projects/cncfglossary/deploys/69581a916f6d6f00088f8d09
😎 Deploy Preview	https://deploy-preview-3608--cncfglossary.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[jihoon-seo]

It seems that the preview works nice.
@Okabe-Junya Thank you for this huge work!

[cjyabraham]

There are some significant shifts in the layout and styles of the site. I just opened the homepage and can see about 6 things that are wrong. Is this meant to be reviewed at this stage or is it still a WIP?

[cjyabraham]

There are some significant shifts in the layout and styles of the site. I just opened the homepage and can see about 6 things that are wrong. Is this meant to be reviewed at this stage or is it still a WIP?

[Okabe-Junya]

@cjyabraham

There are some significant shifts in the layout and styles of the site. I just opened the homepage and can see about 6 things that are wrong.

If you notice any problems, please point them out specifically. I moved this PR from draft to ready for review, so this state is intentional.

I am aware of the minor layout changes, such as the addition of a globe icon to the left of “English (i18n drop down)” and the new “Create child page” and “Report issue” buttons.

Do you think these minor changes resulting from the docsy/hugo update unacceptable? (Or you mention another wrong place?)

[cjyabraham]

I think the new "Create child page" and "View page source" links are ok to leave but fine to remove as well if we want to keep the list as simple as possible.

As for the render issues, here is an initial list. I think they all deserve fixing. We spent a lot of time and money working with a design firm to establish the current brand across all CNCF sites and it would be a shame to allow it to degrade:

1. The left padding of the main column of text is too small
2. The background color behind "Search this site" should be grey, not white.
3. The text of the menu items should be black, not grey
4. The spacing of the menu items needs to be larger to match the live site
5. The position of the site logo is too far right
6. Remove the globe icon beside the language dropdown
7. The background color for the rectangle at the bottom of the left sidebar term listing should be grey, not white.
8. The right padding on the footer content has been removed

[Okabe-Junya]

Thank you, I didn't know these background details.
At least, I have no intention of deliberately changing the style.

But my concern is that many CNCF sites still have the old docsy theme remaining in their repositories as git submodules. Given compatibility with Node, Hugo, Netlify, etc., it wouldn't be surprising if these break at some point.

Is there a plan to update these across the entire CNCF? If there are already guidelines or like this for migrating while preserving the style, I'd be happy to follow them

[cjyabraham]

I don't think there's a plan yet to upgrade these sites.

[Okabe-Junya]

Thanks, anyway, wouldn't it be a good idea to get ahead on updating docsy on this site?
I respect the CNCF brand and your contributions, but I think (continuios) software bumps are also important topics.

I'm welcome to contribute on this topic. Please lmk if there's a need to discuss this within CNCF (I can participate in the discussion if needed)

[Okabe-Junya]

Also, please wait for a bit for fixing some part.
I plan to fix this PR in next weekend (since I need to focus on some other things in next week 🙇 )

[cjyabraham]

I'm not sure I see the need to keep the docsy theme up-to-date, especially since the new versions break the UI of the site. Are there particular features you're wanting from the new version of docsy? Or did it solve some security issue?

I'm all for staying up on the latest versions of core software libraries but, since docsy is just a theme, I wonder whether the same principle applies.

[Okabe-Junya]

From a maintenance perspective, I definitely want to remove the docsy submodule from the repository and update to docsy 0.7.

This is because migrating to Bootstrap 5 is critical for security (even sites served as SSG can be affected by XSS, etc.). c.f.

• https://getbootstrap.com/docs/4.6/end-of-life/
• https://github.com/google/docsy/releases/tag/v0.7.0

As you mentioned, we would reconsider whether updating to 0.13.x (docsy latest) is necessary. Initially, I also intended to update to the 0.7.x (as indicated by the branch name), but search and several features didn't work. After testing several versions, updating to 0.13.x resolved the issues, so I proceeded with that update

[Okabe-Junya]

However, from an accessibility perspective, updating to the latest Docsy version from 0.7.x is well-justified.

Looks CNCF Accessibility Statement commits to WCAG 2.1 Level AA. The Docsy 0.7 ->0.13 bump includes some improvements that directly support this commitment:

• Docsy 0.9.0: added underlines to links by default, addressing WCAG 1.4.1 (Use of Color)
• Docsy 0.13.0 improved color contrast by falling back to Bootstrap's default colors, which are required by WCAG 1.4.3 (Contrast Minimum).
• (and some other improvements including these updates)

[Okabe-Junya]

So I think we need to consider the trade-offs between these (target-based) accessibility improvements and the CNCF brand image and design. Do you have any thoughts on this point?

(Of course, it would be ideal if these weren't trade-offs, but I think it's difficult to make updates without any changing the site's structure at all.)

[cjyabraham]

If there are any accessibility improvements we can make, could you start a new issue that lists them and how we might be falling short of the standard? Back when we came up with the brand for CNCF we made a lot of effort to be compliant but may have missed one or two points. In some cases we may have deliberately made a small concession on accessibility for the sake of the design.

I agree we should update Bootstrap if that fixes a security issue. Is it necessary to update docsy to accomplish that or can we go directly and update Bootstrap ourselves?

[Okabe-Junya]

Thanks, I'll create a issue, so please wait for a bit 🙇