[Tracking] Upgrade Docsy

[chalin]

Why upgrade Docsy?

The main reason is that the Bootstrap (BS) version used by this repo's Docsy theme (which dates back to 2020!), reached end-of-life last year, and so BS will not be receiving any more upgrades, not even security patches. Also, Docsy has receiving a lot of enhancements and fixes since 2020 -- in particular it no longer has recursive submodule dependencies!

Why this repo?

A number of TAG and other websites share the version of Docsy used in this repo. After discussion with @cjyabraham and @nate-double-u, we agreed that this repo might be a good candidate for exploring the Docsy upgrade. As I mentioned above, the local Docsy files are from Nov 2020, and have custom changes applied on top of that. It would be much better if an official release of Docsy was used instead, and if we moved any customization into repo-specific files (which is the recommended way of using Docsy).

Benefits

If / once the Docsy upgrade happens, this repo might be used to inspire & inform a CNCF website-starter template.

Impact?

My goal is to explore the Docsy upgrade in a way that is the least disruptive as possible, in particular, that the website will continue to auto-publish based on submitted content, and that there will be no other changes to the site's content or appearance¹.

Comments?

Comment here if you have any questions or concerns. You can also reach out via the CNCF #techdocs channel.

/cc @caniszczyk @cjyabraham @nate-double-u @leonardpahlke

Prep & site rework

• [CI] Get Hugo via package, make submodule fetch automatic, cleanup .gitignore, etc #155
• Adds link checking and fix broken links #166
• [CI] Enable markdown linter and fix reported issues in *.md, */*.md, and website/content #169

Tasks

• Reintroduce Docsy as a submodule #160
• ...

Related

• Website Hugo+Docsy revamp tag-contributor-strategy#402
  • Don't use a fork commit for Docsy tag-contributor-strategy#399

Footnotes

1. No change in appearance to anyone who isn't a fontend designer. Some minor changes in appearance are to be expected, since Bootstrap and FontAwesome have changed since 2020, with impacts on glyphs, font sizes, spacing, etc. ↩

[leonardpahlke]

Sounds good to me, thanks!

[leonardpahlke]

Looks like this issue is completed ✅, is this correct @chalin? Thanks so much for upgrading the website!

[chalin]

Hi @leonardpahlke - no, this is far from complete. What has been accomplished is to Reintroduce Docsy as a submodule #160, which is an essential first step, but Docsy has not be upgraded yet. Such an upgrade is a nontrivial undertaking given the numerous style and layout overrides that exist. I'm unsure if/when I'll have the time to look into this; it might not be until 24Q2.

As I've mentioned elsewhere, it might be easier to start from the latest Docsy (0.8.0 as of the time of writing) and (re-)create the site style from this fresh new base. If there are any frontend designers willing to tackle that, I'd be willing to contribute my Docsy knowledge.

/cc @nate-double-u @krook @caniszczyk

[leonardpahlke]

Thanks for the insights @chalin !