10 Reasons to Use Docusaurus for your Docs, Blog & Marketing Site
Recently, I’ve been working on a project called sapling.dev, which generates full stack JavaScript (node + React) apps, including full CRUD APIs, Auth0 and Stripe integrations, and more. Sapling is the first developer tool I’ve built, and I quickly realized that the following items would be critical as we begin marketing:
- Top-Notch Documentation — our Docs need to describe how users can generate a new codebase, how the new frontend and backend are structured, how to get up and running (npm scripts, nvm versioning, dockerized database, etc.), and how to configure the integrated services like Auth0 and Stripe
- A Nice Blog Section — Sapling aims to help developers build quickly and follow best practices, so we definitely want to continue adding posts to serve as tutorials for choices made in generated codebases
- General Marketing Content — like anything else, we need some arbitrary pages like a home page, a pricing page, etc.
We didn’t want to re-invent the wheel — any attempt we’d make at designing Docs or a Blog would fall well short of sites I’ve spent time on recently like React Native Docs or Auth0 Docs.
We knew it would be ideal to write mainly in Markdown, and then learned about MDX, which lets you add React components to Markdown. With a little more research, and after trying a couple alternatives (see the end of this article), we stumbled upon Docusaurus.
What is Docusaurus?
Docusaurus is a Facebook Open Source project that makes it super easy to build a website focused on content — i.e. Docs, Blog and more. Out of the box, you get a home page, a Blog with some sample posts, and a Docs section with some sample docs.
Note: when I created my Docusaurus project, I used the classic template, i.e. @docusaurus/preset-classic… there are a few options, but this gives you the major pieces I mentioned above and dive into below.
Docusaurus relies on specific structure and configuration to make it easy to add and organize content. I’ll get into the details below, but a lot of configuration lives in the root file docusaurus.config.js. For the Docusaurus-specific use case of React / Markdown content generation, I found it to be extremely fast and easy.
For our Sapling project, we keep our static Docusaurus site and our core application separate. Our Docusaurus site is hosted at the root domain sapling.dev, which guarantees that our home page and content is super fast (static, using s3 bucket + Cloudfront), and then we host a Create React App application (where users configure and generate codebases) at app.sapling.dev.
10 Reasons to Use Docusaurus
In no particular order, here are 10 things I like about Docusaurus:
- Static Site Generation (SSG)
When you run a build command in your Docusaurus project, it’ll build static HTML pages that are ready to serve to browsers. Since static pages don’t change (e.g. your blog post will look to same for everyone who looks at it), they’re ideal to cache in a CDN like AWS Cloudfront or similar services. Loading up the pages of your static Docusaurus site will be really fast.
2. MDX Ready to Go
As noted above, MDX is Markdown with the ability to render React components. These are .mdx files rather than the plain .md.
For any of Blog posts, Docs pages, or arbitrary pages in Docusaurus (more on those, soon), you can write content easily thanks to Markdown, and throw in some React components where needed. This flexibility proved to be great for making our site — as an example, the Sapling pricing page is a .mdx file. It uses some markdown for text along with a React component, which shows the pricing options in React + Material-UI.
3. Docs Section
Docs are one of the core competencies of Docusaurus. With very little work, you can have great-looking Docs like we made for Sapling.
All you need to do is follow these 2 steps:
a. Add a .md or .mdx file in the docs folder
b. In the sidebars.js file, you add the id of that new Markdown file (more on that in a second) to one of the categories defined in sidebars.js.
Let’s see how that works…
Consider adding a new file in the docs folder called overview.md. You can add special info to the top of the file like this (the metadata at the top won’t display on the page itself):
---
id: overview
title: Overview
sidebar_label: Overview
slug: /overview
---## Welcome to my Project
This is Markdown in a docs page...
The id property called overview can be added to the sidebars.js file, and from there your /docs page will display the new page in the left bar, and the page will be viewable at /docs/overview.
One of my favorite features you get with each doc is an outline on the right hand side, which creates links to different major sections of the doc according to the nested Markdown headers you use.
Docusaurus also creates “Next” and “Previous” UI links at the end of each doc page so that the user can go forward or backwards easily through your docs.
Note it’s possible to make your site “Docs-only” in case that’s your only goal — check out official docs.
4. Blog Section
Similar to Docs, the Blog is another major core competency of Docusaurus. Our Sapling Blog looks very well-done without any custom work.
Just like with Docs, you put .md or .mdx files into the blog folder. You add metadata like so (see docs for full list of options):
---
slug: introducing-sapling
title: Introducing Sapling
author: Nate Jones
author_title: Co-Creator, Sapling
author_url: https://github.com/<my-github>
author_image_url: <my-image-url>
---## Full Stack JS
The blog post markdown content...
The title will appear on your Blog’s left bar, and the url /introducing-sapling will go to your new post.
The file name itself should encode the date as mentioned here in the official docs.
By default, when you access the /blog/ path (no specific blog link), you’ll see a listing of all the blog posts on one big page. This can get really long, and one way to customize and make it look nicer is to use the special <!--truncate--> syntax somewhere in your Markdown — only the content above <!--truncate--> will show up on the “preview” view before the user actually clicks in.
There is a “Blog-only” mode as well.
5. Well-Designed Home Page Generated
The index page of your Docusaurus site will look pretty similar to the Flux page. The page takes into account some configuration from your docusaurus.config.js including project name, description, and more.
This is the first example of an arbitrary page (see next point in the list), but happens to be created for you. You’ll see next that this page’s file location at src/pages/index.js has special meaning when it comes to routing. For Sapling, we swapped the generated home page out with our own custom page.
6. Arbitrary Pages with Automatic Routing
If you’re wondering “Can I add any random pages I want beyond Docs or Blog?” the answer is yes!
Routing is handled based on filename. If you’d like a page on your site at the route /faq, simply add a file under src/pages/ called faq.js (or faq.md / faq.mdx) and you’re good to go.
As mentioned above, our pricing page is a .mdx file — since the url is /pricing, that means we have a file called src/pages/pricing.mdx, which contains some Markdown and React code. In fact, .mdx files are nice for arbitrary pages because Docusaurus knows to keep the header and footer in tact for these.
See the info below on the Header and Footer config, but ultimately we add some Header configuration to make sure we have a link to our Pricing page.
7. Theme & Custom CSS
The default docusaurus.config.js links to a file called src/css/custom.css — this file shows you how to create some global CSS to apply to the entire site.
One immediate change we made was to update the default colors — check out the docs on this, here.
Beyond global styles, you can still create individual CSS files for different React components as you’d expect. Our site uses .scss files more local to the React components on our home page.
8. Header & Footer Configuration
The navbar in the Header can be customized with links and more. You can customize your logo, add links to your custom pages beyond Docs and Blog, and position as desired. We removed the out-of-the-box dark mode toggle since it didn’t fit in well with our theme (in the Docusaurus config, we switched themeConfig->colorMode->disableSwitch to true).
Similarly, the footer is set up with some links to various Docs, some contact and social info, and a “More” section. I customized the Docs portion of the footer to point to the major categories in our site’s Docs for ease of use.
9. Plugin Ecosystem
Docusaurus is extensible with a plugin system. A couple of plugins that we’re using initially are docusaurus-plugin-sass to style with .scss files, as well as a built-in Google Analytics plugin.
In a similar vein, you might be used to adding certain scripts or CSS files in the HTML head (e.g. in Create React App, you have access to a public/index.html file). Though you don’t have that file here, Docusaurus allows you to use this import:
import Head from '@docusaurus/Head';In the Head React component, you can add a script like the following, which is the script we use to add the live chat pop-up on Sapling (this is through our HubSpot account):
<Head>
{/* <!-- Start of HubSpot Embed Code --> */}
<script
type="text/javascript"
id="hs-script-loader"
async
defer
src="//js.hs-scripts.com/<some-id-number>.js"
></script>
{/* <!-- End of HubSpot Embed Code --> */}
</Head>We use this Head component in our src/pages/index.js file from Docusaurus.
10. Great for Open Source Projects
In your docusaurus.config.js file, you’ll see various configuration related to your project’s GitHub url. Since Sapling isn’t OSS, we removed some of this info. When you do link to GitHub, you’ll have out-of-the-box functionality for users to make edits to blog posts or doc pages, which will tie back in with your GitHub repo.
Many big projects like React Native and Flux use Docusaurus, so it’s built to be the ideal way to build OSS project content.
Alternatives
There are solid open source and paid for options to set up Docs and/or Blogs and/or other content. Here are just a few to check out:
- Gatsby is a really popular framework / tool to build fast, statically-generated sites. Here’s a plugin to use MDX in Gatsby
- GitBook is a freemium option that focuses on building really nice Docs
- Other SSG tools like Next.js are really flexible, too
These are all good options, but since our explicit goal was to create a static site for Marketing, Docs and a Blog, with great Docs/Blog design out of the box, I found that Docusaurus was by the far the easiest way to get going, with almost no learning curve.
