Skip to main content

Apps with Docusaurus 2.0 and React

· 6 min read

Writing good documentation is a mission-critical aspect of building software these days. Whether you are writing something for yourself, for the Open Source community, or your company, it's essential to keep things documented for good reasons:

  • It makes developers more productive since they can rely on the docs to understand how to use your software.
  • It makes developing the software itself easier promoting knowledge sharing amongst developers.

5 good reasons to pick Docusaurus​

The process of writing documentation it's often tiresome. Imagine if you need to worry about building the whole foundation to make your documentation available to the public. Amongst many options to provide such foundation, I enjoy Docusaurus the most because:

  1. It's opinionated, provides you with all the structure you need to ship content fast. Docusaurus will decide how to structure your content, manage plugins, etc.
  2. Allows further customization with React. You can apply your knowledge of React to extend your documentation with other UI components built in React, as you see fit.
  3. It's Markdown all the way. Just like Gatsby or Hugo, the seamless interpolation with Markdown makes the experience of writing docs a breeze.
  4. It's GitHub pages friendly. GitHub pages are one of the sweethearts of free website hosting, especially when hosting documentation for open source projects. It's easy to set up and super convenient. Docusaurus docs have a guide just for this purpose.
  5. Strong orientation towards documentation; this is why I would pick Docusaurus to write docs over and over again. The sharp focus on documentation makes the whole solution even more attractive since you'll find the default way pages are structured very suitable to write documentation. Of course, the Docusaurus ecosystem is vast; simply looking at their showcase page to understand its use goes way beyond simple static documentation websites.

Tips to work with Docusaurus​

Here are a few tips & tricks that will help you build Docusaurus sites, get past some technical challenges, and better know what Docusaurus has to offer.

MDX support​

MDX is fantastic. It allows you to interpolate Markdown with JSX (React components). It's incredible to be able to simply plugin a React component. Here's a snippet from this blog post markdown file, where we include a React component to collect feedback at the bottom of the article.

---
slug: app-docusaurus-react
title: Apps with Docusaurus 2.0 and Reacttags: [Documentation, JavaScript]
---

import BinaryFeedback from "../src/components/binary-feedback";

<BinaryFeedback />

<!-- ... (rest of the content) ... -->

Built-in blog post features​

You're reading a blog post built on Docusaurus. We use the Blog features to create content. Most things will be there waiting for you to start; add a markdown file under the blog/ folder and start typing!

Use site context hook​

Probably one of the handiest features is the ability to access the content of your docusaurus.config.js through the context React hook. Here's a small component that builds a social media sharable link using information from the config file (this same link produces the sharable paragraph at the bottom of our articles).

import React from 'react';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

export default function ShareHint({ postPath, postTitle }) {
  const { siteConfig } = useDocusaurusContext();

  if (!postPath || !postTitle) {
    return null;
  }

  const fullUrl = `${siteConfig.url}${postPath}`;
  const url = `https://twitter.com/share?text=${postTitle}&url=${fullUrl}`;

  return (
    <p
      sx={{
        mt: 3,
        fontSize: [1, 1, 2],
      }}
    >
      If you liked this article, consider sharing (
      <Link href={url} rel="noreferrer" target="_blank" title="tweeting">
        <span style={{ textDecoration: "underline" }}>tweeting</span>
      </Link>
      ) it to your followers.
    </p>
  );
}

Running JavaScript globally​

Initially, it was not clear how I could execute some JavaScript on every page. Because everything is segmented and you don't have access to index.html to add globals to your application. An alternative would be to ship your global code, i.e., code that you want to run on every page (e.g., a cookies banner component) in your theme/Footer/index.js. Because Docusaurus includes the footer in all pages, you can write logic that will execute every page, for example, by mounting a React component.

Conditionally applying CSS classes​

I became aware of the existence of clsx while working with Docusaurus. Look at it whenever you're in need to apply some CSS class conditionally. Here's a small example.

// ... some render method
return (
  <footer
    className={clsx('footer', {
      'footer--dark': footer.style === 'dark',
    })}>
  ...
  </footer>
);

The class footer--dark would be applied if the condition footer.style === 'dark' is met.

Just with a plain JavaScript object, you can tell Docusaurus how to structure your footer. Here's an example. And here's how it looks.

People delete sites and move sites all the time. It's an awful experience to read a page, click on a reference, and end empty-handed, facing a blank page. Docusaurus offers an out-of-the-box solution to scan for broken links. I highly recommend the usage of onBrokenLinks to warn you of broken links in your content; this will make it very hard or even impossible for you to ship broken links! Here's how to configure it in your docusaurus.config.js.

module.exports = {
  title: 'tweak browser extension',
  // ...
  onBrokenLinks: 'throw',
  // ...
};

Redirect routes easily​

If you are migrating from another stack and plan on introducing new routes, this small redirect trick will be super useful. You can redirect old routes to the new ones by creating a simple markdown file with the name of the old route, and redirect users to your shinny new page.

---
title: My Old Title
---

import { Redirect } from '@docusaurus/router';

<Redirect to="my-new/fancy/page/route" />

Analytics support​

It's super easy to set up analytics with the plugin-google-analytics. Here are the steps:

  1. Install the plugin
  2. Add append this object into your docusaurus.config.js

That's it!


And that's all. I hope the above tips unblock your journey of content creation with Docusaurus.

If you liked this article, consider sharing (tweeting) it to your followers.


Did you like this article?