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:
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
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.
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.
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)
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!
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! 🚀)
Despite all the positive aspects of Docusaurus we experienced some obstacles:
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.
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.
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.