proposal: Use docusaurus to build our website

[Xuanwo]

Our current website framework is mkdocs which is lacking blog support. So I propose to use docusaurus to build our website.

Docusaurus is maintained by Facebook Opensource, and is widely used (see showcase: https://docusaurus.io/showcase). It's easy to add a new module like blog and so on. Also, it has built-in multi-version support, i18n support. And we can extend it via writing a new React module.

More, maybe we can apply for vercel open-source sponsor so that we can deploy on vercel instead of github pages. After that, we can remove the gh-pages branch and the github pages workflow, we can have a PR preview of our website to avoid broken changes.

[sundy-li]

Good topic.

Actually, the first version of databend's website is using docusaurus :)

[sundy-li]

I don't know, maybe @BohuTANG can answer this question.

[BohuTANG]

Then we changed to Material for MkDocs as you see https://databend.rs 😆

[sundy-li]

I think mkdocs.yml is hard to maintain the nav. I'd like it to be auto-generated.

[BohuTANG]

We plan to have a blog, docusaurus seems better than Material on it

[Xuanwo]

Yep, docusaurus support auto-generated nav. Take beyondstorage as an example: https://github.com/beyondstorage/site/blob/master/docs/go-storage/sidebars.js

The result: https://beyondstorage.io/docs/go-storage/index

[Xuanwo]

Hello everyone, I tried to migrate our site to docusaurus, here are some demo show.

If they look good, I will start to do a real migration.

In this migration, I will:

• Try my best to not break any doc link (so all references will not be broken)
• Try my best to keep current content organization.

However, I don't have much experience in front development, so

• Current databend.rs design could not be migrated.
  • I will use the default theme instead
• The page layout could be changed.

And, in order to make our site run well, we need to apply for vercel and algolia's open-source sponsor. So that our site will have PR preview and full text search support.

[PsiACE]

LGTM

[PsiACE]

I was working on this before, but unfortunately my attention quickly moved elsewhere.

• How to better organise existing documents? Some division may be required, such as separate user manuals and developer documentation.
• How to manage blogs published in different languages?

[Xuanwo]

How to better organise existing documents?

I have no idea so far, so I prefer to keep current style.

How to manage blogs published in different languages?

It's a docusaurus builtin feature: we can have an i18n blog.

For example:

• en-US: https://beyondstorage.io/blog/2021/09/26/2021q4-roadmap
• zh-Hans: https://beyondstorage.io/zh-CN/blog/2021/09/26/2021q4-roadmap

[PsiACE]

emmm, Ok, I think we can migrate to docusaurus and look forward to your PR. As this is likely to be a relatively large change, it is best to be able to have a preview at the time of PR.

[Xuanwo]

Ok, I'm creating a tracking issue for this discussion: #3209

[Xuanwo]

With the help from @Chasen-Zhang, we got https://databend.rs online now!

[sundy-li]

Code highlight is not auto detected.

https://databend.rs/user/system/

[Xuanwo]

Sadly, docusaurus doesn't have language auto-detect feature. I will add them one by one to fix it.