Why I’m using Docusaurus to build my blog
It’s 2022 and I’ve finally gotten around to updating my personal website and blog. A lot has changed since I last created a new website for myself in around 2019, using just plain HTML and CSS for the home page, and WordPress for the blog. I’ve chosen to develop my new site using Docusaurus, and while this may raise a few eyebrows, in this post I’m going to go explain why.
Why Docusaurus?
Time to Hello World!
Docusaurus is crazy fast to set up. It provides you with all of the tools you need out-of-the-box to start writing content. As it was created for writing developer documentation sites, you are basically already set up to start producing content as soon as you create your site.
Here‘s some handy things you get with Docusaurus out-of-the-box:
- Write content in Markdown and MDX
- Dark mode
- Blog plugin
- Swizzling - map your Markdown to custom React components
- Versioning
If you were to create a developer blog in say Create React App or Next JS, you’d have to set up and maintain all of this functionality yourself!
Write in Markdown
Docusaurus allows you to write blog posts and (even pages!) in Markdown. Writing in Markdown is a great way for developers to write content, without the need for a bulky CMS. The Markdown content is formatted according to your Docusaurus theme and CSS, and you can also customise how it gets formatted using a process called swizzling where specific Markdown constructs are mapped to specific React components.
MDX builds on Markdown by allowing the use of React components within your Markdown files! This is a great way to add pieces of interactive content to your blog posts, or other custom code.
Backed by Meta
When choosing a particular framework or library to use, it helps to think about its potential longevity and long-term support. While it’s tempting to jump on the latest framework that’s hot-right-now, there are many that can come and go extremely quickly. Usually there are several other projects doing similar things, and only one or two will win-out and survive longer term.
One thing I look for when choosing open-source frameworks or libraries is who the maintainers are, and whether the project is backed by a reputable company. Docusaurus was created by a team of engineers at Meta (a.k.a. Facebook) for their internal documentation sites, and they are actively developing it. As Meta were the original creators of React, their open-source projects have a great reputation. An added bonus is that as both React and Docusaurus are in principle maintained by the same organisation, we can expect there never to be any dependency issues between the two, and that their respective roadmaps should be aligned.
Community uptake
Many high profile companies, organisations and projects have switched to Docusaurs for their websites or documentation sites. Here are a few examples:
Performance
Docusaurus sites are very snappy and fast. As Docusaurus is a Static-Site-Generator (SSG), the browser receives static HTML and CSS files from each route so that a visited page is visible even before JavaScirpt has loaded.
Additionally, its Link component makes use of preloading, which means that often by the time a user clicks on a link, the resources have already been fetched and are available for a super quick page load.
Accessibility
One of the first things I noticed about Docusaurus was a dark-mode feature out of the box!
This is a great feature as it allows users to choose whether they prefer a light or dark theme for their reading. As an example, if someone is coding on a dark-themed editor, they may find switching back-and-forth to a light-themed docs site to be jarring.
So far I’ve found Docusaurus sites to be very accessible, but there are things I want to do in the future to make it even better. Some things include:
- More consistent and prominent focus-indicators
- Make external links not opening in a new tab (if this happens without warning to users of assistive technology, it can be disorienting)
Drawbacks
As Docusaurus sites are primarily designed for documentation sites, there are a couple of drawbacks to using it primarily as a blog:
- No out-of-the-box social media sharing buttons/integration
- No out-of-the-box comments system
Conclusion
My experience using Docusaurus so far has been great. The speed of setup, and the quality of documentation make it stand out as a great project. There will likely be issues along the way as I further develop the site, but I have confidende in the maintainers and community. I look forward to the official v2 release.
Thanks for reading the first post on my new site. I plan to post on topics such as web development, software, technology, and productivity. If you enjoyed it, give it a share!