Migration to docsy theme

[yurishkuro]

Jaeger website today is using a completely custom theme. This creates a maintenance headache as we run into various layout bugs (e.g. #744, #745). We also have issues with some old dependencies for CASS like bulma (#730).

I looked around in other CNCF projects and noticed that both OpenTelemetry and Kubernetes websites are using https://github.com/google/docsy theme, which is likely much better supported.

Of course, it's not a very trivial job to replace the theme, as we also have plenty of CSS customizations that we would want to keep. So before we really decide to do that we need some investigation, e.g. just trying out enabling the docsy theme and spot-checking what would break in Jaeger as a result, and collect the findings into a report.

One thing we'd need to do is customize the color schemes to match the existing Jaeger website (https://www.docsy.dev/docs/adding-content/lookandfeel/)

---

Questions to clarify requirements & design objectives

• [IA] Questions about versions,latest, and next releases #892
• [Docsy] SEO: mark non-latest docs as noindex nofollow? #910
• [Docsy] Multilingual support? #911
• ...

Prep & clean up

• Hugo.yaml cleanup: drop unused navbar param #894
• Update to Hugo v0.147.6, adjust theme css integrity #895
• Fix project title etc in Hugo config #896
• Consolidate NPM packages and more:
  • Add Docsy as NPM package, consolidate all NPM packages, refactor & tweak spell check scripts #903
  • Update ci-test.yml: drop unnecessary with: submodules #905
• [cleanup] Drop 1.x draft and empty pages #904
• Navbar partial whitespace cleanup #901
• Config refactoring, and more navbar cleanup #908
• [Bug]: Migration page shows up in two places in the 2.0 docs #915
• ...

Tasks

• Add Docsy as NPM package - Add Docsy as NPM package, consolidate all NPM packages, refactor & tweak spell check scripts #903
• Organize doc pages per major version without affecting site gen #909
• Fix doc page front-matter attribute values for Docsy #912
• Set up the docsy branch:
  • Create docsy branch
  • Adjust build instructions to use hugo.docsy config
  • Configure site preview
• [IA] Reorg versioned doc pages: make file system org match IA org #913
• ...
• Drop pre-docsy front matter that is no longer needed, such as hasParent, etc.
• ...

[Dindihub]

Hi, @yurishkuro Did you get help with this issue? I worked on a similar project for theupdateframework during my LFX mentorship program Term 2 2024. I would be glad to assist.

[yurishkuro]

@Dindihub We do need help.

[chalin]

/cc @nate-double-u, since we talked about this during our techdocs call this morning. @yurishkuro - we were curious if you had create a ticket for this?

Btw, @Dindihub contributed to the bulk of the base work of the following:

• New and improved Docsy-based version of the website  theupdateframework/theupdateframework.io#105

I'm about to wrap up the Docsy migration for the in-toto project. I plan to look into what would be involved for this project. Maybe @Dindihub will look into it before then too.

[yurishkuro]

we were curious if you had create a ticket for this?

@chalin sorry, I didn't follow - are you asking about the JIRA ticket I opened long time ago? That one was more about informational structure review / recommendations (especially since we just rolled out new documentation for Jaeger v2).

[chalin]

Thanks for the context. I was wondering if you had opened a new ticket that I might not have been aware of (not an obligation of course).

[yurishkuro]

@chalin fwiw upgrading to docsy would be much higher priority

[Dindihub]

/cc @nate-double-u, since we talked about this during our techdocs call this morning. @yurishkuro - we were curious if you had create a ticket for this?

Btw, @Dindihub contributed to the bulk of the base work of the following:

• New and improved Docsy-based version of the website  theupdateframework/theupdateframework.io#105

I'm about to wrap up the Docsy migration for the in-toto project. I plan to look into what would be involved for this project. Maybe @Dindihub will look into it before then too.

Noted. Thanks @chalin

[chalin]

@yurishkuro - we're discussing this as possibly in scope for 2025. Btw, I'd remove the good first issue label since this work requires a lot of expertise, and is an undertaking that will span weeks.