Why Docusaurus

When we introduced our chapters as part of our circle based structure, we had the idea to publicly announce what our chapters are doing, what technologies they are using and how they are working. When it came to the tooling decision, Docusaurus came up pretty quickly as it comes with multiple features that fit our technology stack out-of-the-box:

React

As React is our front end javascript library of choice, it felt quite familiar to extend Docusaurus to our needs.

Markdown

Docusaurus articles can be written in Markdown syntax. This also allows "non-tech" colleagues to quickly get into writing articles without the need to learn JSX - a syntax extension for JavaScript used by React. Additionally, our colleagues are used to work with GitLab, which is also using Markdown as markup language in their editor.

Document versioning

Docusaurus comes with document versioning for its documentation plugin which helps keeping track of changes inside the chapters e.g. changes in technologies or processes.

Multiple documentations

Through its configuration file, Docusaurus can be used to serve multiple documentations: This is an important feature, as we have multiple chapters and therefore multiple chapter documentations that need to be maintained by different people.

Already styled

We could get rid of almost all styling workload as Docusaurus already comes with some neat styling that can be easily adapted in most cases (See Cons)

SEO

Docusaurus provides a convenient way to add SEO (search engine optimization) to our pages. In fact, every author can add custom metadata to his blog entries inside his Markdown file!

Performance

Docusaurus is a static site generator: It creates separate .html files for each page (e.g. a blog entry) which significantly increases the performance of the pages compared to other approaches like SPA (single page application) or SSR (server side rendering).

...and a blog?

When we had our internal discussions about the tooling for the chapter page, our very own Stephan Hochdörfer came up with the requirement of a new blog engine (Read more on his post about the migration from Silverstripe to Docusaurus) which Docusaurus also covers.

Of course there are even more features provided by Docusaurus, like Internationalization or a Search which by the time of writing have not been required (stay tuned! 🚀)

Cons

Despite all the positive aspects of Docusaurus we experienced some obstacles:

Writing articles

People who want to write blog articles will have to set up the docusaurus project locally, create new folder(s), files etc. to get a preview of their articles. This requires a local setup of node and a node package manager (like npm or yarn). We are currently working on a more seamless flow to write articles for all authors.

"Infima"

For more complex layouts, the styling framework used by Docusaurus ("Infima") is a little limited. For our use-case it would have been better if Docusaurus had stuck to a CSS framework like Tailwind CSS.

Conclusion

Using Docusaurus is a breeze - all the features it provides feel well-chosen and meaningful. The time it took us to set up a blog and multiple documentations was impressively low.