feat: migrate docs to docusaurus

[jasperdekeuk]

Is your feature request related to a problem? Please describe.

No, this is a very opiniated feature request and really don't hesitate to disagree with me! 😉

Describe the solution you'd like

I think the docs could benefit from using Docusaurus instead of Docsy. Docusaurus has a lot of out-of-the-box features (like decent versioning, blog, plugins, better mobile support, cli etc.) and is very much more actively maintained then Docsy. There is a lot in the kairos docs, but I think the useability could be improved with Docusaurus.

Describe alternatives you've considered

MKdocs, Hugo... All very simple, but the size of Kairos is becoming to big for simple documentation solutions and needs a more extended framework like Docusaurus imo

Additional context

I was very curious on how much effort it would take to transform a Docsy to Docusaurus, so I gave it a very quick and dirty attempt -> https://jasperdekeuk.github.io/kairos-docs/docs/next/category/examples It still needs a lot of work to actually have it ready, but gives a first impression

My main motivation was to see how docsy works and how easy a migration would be, so really don't hesitate to say that it is not interesting, I really wouldn't mind throwing it away 😉 if it would be interesting I also wouldn't mind continue working on it

[mauromorales]

Thanks for opening this issue @jasperdekeuk. Overall, the team liked the theme with Docusaurus, just @jimmykarily is out so waiting on his feedback too.

Once we know if the team is on board for the change, we can discuss implementation together with you, since you already made quite some progress.

Keep in mind that December is a low month cuz of holidays so we might get back to you a bit later

if we implement this change we should also do it for https://kairos-io/hadron

[jimmykarily]

It looks good to me (some polishing is needed here and there as said). I would like us to document what the benefits of the migration are (an explicit list would be nice), to make sure we are not jumping from one thing to the other with no clear goal. Some of the listed features, we already have (e.g. versioning). If docusaurus makes things easier, that's fine too. Let's just write it down.

[mauromorales]

yeah I'm not sure how docusaurus versioning works but docsy one is there but kinda broken, is the reason why we need the complex release scripts. By default docsy does this via subdomains, but we don't have that ability with how Netlify is currently configured, we tried doing this but it was problematic so we decided to do it as sub-directories but it's hacky there.

@jasperdekeuk can you quickly explain how the versions work? ideally we just display the latest version per major/minor/patch

and I agree with @jimmykarily it would be good to list the major reasons/benefits why we would move, so maybe you can describe what are the x features that you don't have with docsy or that are just bad experience with docsy that you get with docusaurus

[jasperdekeuk]

Docusaurus versioning is described here: https://docusaurus.io/docs/versioning
It is basically a simple cli that copies the files to a versioned folder and makes sure the navbar and everything is setup for navigation.

An extra possible interesting thing is that you can do multi-instance docs. So have Kairos-docs and Hadron-docs all in the same repo, but have them as seperate docs instance and thus easily have separate versioning as well -> https://docusaurus.io/docs/docs-multi-instance

Describing the benefits is ofc a bit opiniated in this case, so feel free to disagree, but quickly noted:

• Full React support in the docs. Could easily add react components. Like e.g. if there would be a simple react component that does a cloud-init check, you can embed it with ease (not that that component is easy to make though)
• Mobile support: the framework starts with a full clean layout, and very strong mobile support (which is a bit less ideal with the current docsy setup imo)
• safely override and customize theme components -> https://docusaurus.io/docs/swizzling
• plugins: easy to add plugins like https://www.algolia.com/ as search engine for the docs.

If you don't like React, there is also the Vue counterpart -> https://vitepress.dev/

[mauromorales]

since we were mentioning other options in the call, here's one I saw the other day that I liked cuz you can do code annotations, but maybe docusaurus can do that too

https://squidfunk.github.io/mkdocs-material/

[mauromorales]

codehike is based on docusaurus if i understand correctly and allows for annotations out of the box https://codehike.org/docs/concepts/annotations

[jasperdekeuk]

Docusaurus has some support for code annotation, mainly just highlighting lines. the mkdocs seems to have more advanced features for annotation though

[jasperdekeuk]

@mauromorales the docusaurus highlighting is described here -> https://docusaurus.io/docs/3.0.1/markdown-features/code-blocks#custom-magic-comments
The entire page is about code blocks, so could be an interesting read.
I'm definitely open for other frameworks as well though.
Seems like codehike can indeed be added to docusaurus

[jasperdekeuk]

Docusaurus also checks all the links in the documentation and will throw errors/warns if they would not exist