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

• [x] #911 - no
• [ ] #892
• [ ] ...

Prep & clean up

• [x] #894
• [x] #895
• [x] #896
• [x] Consolidate NPM packages and more:
  • [x] #903
  • [x] #905
• [x] #904
• [x] #901
• [x] #908
• [x] #915
• [ ] #985
  • [ ] #910
• [ ] ...

Tasks

• [x] Add Docsy as NPM package - #903
• [x] #909
• [x] #912
• [ ] Set up the docsy branch:
  • [x] Create docsy branch
  • [ ] Adjust build instructions to use hugo.docsy config
  • [ ] Configure site preview
• [x] #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:

• https://github.com/theupdateframework/theupdateframework.io/pull/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.

[yurishkuro]

@chalin removed good first issue. When do you expect to come to a decision and have clarity on the timeframes?

[chalin]

@yurishkuro - before year's end. Either @nate-double-u or I will reach out (possibly via Slack and or the Jira ticket open for this repo).

[chalin]

@yurishkuro - in case you are wondering: I'm spending some initial time studying the current website information architecture (IA), custom theme, layouts, etc. Working on peripheral tasks (like external link checking), not directly related to the Docsy migration, is a practical and useful way for me to get a deeper understand of the site features, so that I can better prepare questions for you, and plan the migration.

Can you assign this issue to me?

[chalin]

@yurishkuro - FYI, I'll be OOO for a few weeks. I'll be resuming the migration as soon as I can.

[chalin]

• Done! 🎉
• Closed by #1023
• Next steps via #1024

[chalin]

@yurishkuro - btw, I've noticed that the new site has better Lighthouse ratings, e.g.:

/cc @nate-double-u

[yurishkuro]

Thanks you @chalin for a massive upgrade of the site! 🚀🎉

[chalin]

I'm glad that you like it. I've tagged some very useful Docsy improvements to upstream. ✨ Thanks for your patience in getting this completed. I'm pleased with the result too. 🙌🏻 As I upstream changes to Docsy, I'll update this repo and remove the Docsy overrides. That will help reduce technical debt and increase ease of maintenance and Docsy upgrades in the long term.