Website Hugo+Docsy revamp

[aliok]

I suggest we don't use Docsy as a Git submodule anymore but as a Hugo module.

Git submodules are complicated to maintain.

Docsy and Hugo recommends using Hugo modules, instead of Git submodules. See https://www.docsy.dev/docs/get-started/#installation-options

I've tried this with https://github.com/cncf/tag-contributor-strategy/issues/397, but that plan didn't work because switching to Hugo modules don't work without upgrading Docsy (and possibly Hugo too).

Plan:

• [x] 1. Do not use a fork commit for Docsy: Currently, the Docsy submodule is at a detached commit that Carolyn created in her fork: https://github.com/carolynvs/docsy/commit/f69a99d7e38a541b74ade9850a813aee26964ba8. There are some changes in the Docsy theme. We need to switch to the attached commit that's before than that (https://github.com/google/docsy/commit/e67775a312f1f3ad32137423fe2b311a397f5293) and find another way to make those overrides. Hugo+Docsy supports overriding layouts and SCSS and I think we can make it work.

  Even though we are going to change to a different Docsy version later on, it makes sense to first go back to a version in Docsy tree first.

  PR: https://github.com/cncf/tag-contributor-strategy/pull/399

• [ ] 2. Upgrade to a later Hugo version

• [ ] 3. Upgrade to a later Docsy version: https://github.com/google/docsy/commit/e67775a312f1f3ad32137423fe2b311a397f5293 is quite old. We need to upgrade to a later Docsy version, but still on the same major version of Docsy if possible.

• [ ] 4. Migrate to Hugo modules: https://www.docsy.dev/docs/updating/convert-site-to-module/ .

• [ ] 5. (optional) Create a bot to update dependencies regularly

• [ ] 6. (optional) It would be really nice to see how the diff of mage build on commit ABC vs commit XYZ. I wrote some instructions with https://github.com/cncf/tag-contributor-strategy/pull/396 , but they're manual steps. Does Netlify support that?

UPDATE: I want to add some instructions here...

• In each step:
  • Run mage build to render the website. This will render html pages in website/public directory.
  • Run the same command in another clone of the repository from main branch. Then compare the outputs. There must be no important changes. Definition of "important" is something that changes any behaviour. CSS improvements and etc. are fine.
  • Check some rendered pages for sanity check.
  • See example PR for step 1 where I have commands to do these checks: https://github.com/cncf/tag-contributor-strategy/pull/399

[cjyabraham]

Just a few comments:

For step 3, I suspect that if you upgrade Docsy there will be some significant render issues with the site due to changes in the underlying CSS, so just be prepared for that. I think I looked into this at one point but decided to stay on the current version as we didn't need any of the new features in the new version of Docsy.

I think Hugo modules and git submodules both have their pros, cons and idiosyncrasies. I'm not sure if one is really any better than the other but don't mind either way.

There's no doubt that the structure of this site build can be simplified somewhat so appreciate the work being done here overall if it leads to a more manageable codebase.

[aliok]

For step 3, I suspect that if you upgrade Docsy there will be some significant render issues with the site due to changes in the underlying CSS, so just be prepared for that. I think I looked into this at one point but decided to stay on the current version as we didn't need any of the new features in the new version of Docsy.

Yes, I made a quick trial and it is not easy. Current Docsy version is 3 years old though, so, we need to update at some point I think. I will still try this.

[aliok]

FYI,

I think there are tasks to do in this TAG which have higher priority and I have a limited bandwidth. I won't be able to go with this work.

Keeping it open for now.

[iiamabby]

I've migrated the site to use Hugo modules with the newest version of Docsy: github.com/google/docsy@v0.9.1 as expected there is significant styling changes with this version, is there a preferred updated tag / ref that's not far from the current version but still an update?

Below v0.7.0 has errors, presumably due to the recent update of Hugo, above 7 also has significant styling changes

ERROR render of "section" failed: "~/repos/tag-contributor-strategy/website/layouts/docs/baseof.html:32:7": 
execute of template failed: template: about/list.html:32:7: executing "about/list.html" at
<partial "scripts.html" .>: error calling partial: 
"/Users/Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/google/docsy@v0.6.0/layouts/partials/scripts.html:82:30": 
execute of template failed: template: partials/scripts.html:82:30: executing "partials/scripts.html" at <resources.Concat>: error calling Concat: slice []interface {} not supported in concat