Using TailwindCSS v3 in Docusaurus in 5 steps

Earlier today I took another look at the Docusaurus tool from the Facebook team which aims to make it very simple to deploy a beautiful documentation site leveraging Markdown files and static site generation.

Unfortunately, I noticed that the default setup didn't support TailwindCSS out-of-the-box despite a github issue that is a few years old. There are a few npm packages (e.g. https://www.npmjs.com/package/docusaurus-tailwindcss) which allow you to leverage TailwindCSS but those packages are using the outdated version 2 (TailwindCSS is version 3 at the time of writing).

The Docusaurus team does have plans to create a TailwindCSS theme but there's no reason why we need to wait!

Fortunately, Docusaurus supports a plugin architecture which I was able to leverage with a few steps in order to utilize TailwindCSS v3 without breaking any of the existing functionality.

Let's get into it!

Want the code? Here's the github repo

Step One - Setup Docusaurus

We'll get started by creating a default docusaurus setup using the following command:
npx create-docusaurus@latest website classic

Step Two - Install TailwindCSS

Since Docusaurus leverages ReactJS, we'll use PostCSS and AutoPrefixer to manage the TailwindCSS configuration. We will do this by installing the necessary dependencies for setting up TailwindCSS using the following command:
yarn add tailwindcss postcss autoprefixer

As per the TailwindCSS docs, you'll need to create a tailwind.config.js file in order to initialize your configuration using the following command:
npx tailwindcss init

Open your tailwind.config.js file and edit it as follows:

module.exports = {
  content: ["./src/**/*.{js,jsx,ts,tsx}"],
  theme: {
    extend: {},
  },
  plugins: [],
};

Step Three - Setup Custom Plugin

We will now create a custom plugin so that TailwindCSS is included in the Docusaurus configuration options. We will do this by adding the plugin option to the docusaurus.config.js file using the following code:

 plugins: [
    async function myPlugin(context, options) {
      return {
        name: "docusaurus-tailwindcss",
        configurePostCss(postcssOptions) {
          // Appends TailwindCSS and AutoPrefixer.
          postcssOptions.plugins.push(require("tailwindcss"));
          postcssOptions.plugins.push(require("autoprefixer"));
          return postcssOptions;
        },
      };
    },
  ],

Step Four - Load TailwindCSS

In order to actually load TailwindCSS with the custom CSS that Docusaurus utilizes by default, we will modify the src/css/custom.css file by including the following at the top of the file:

@tailwind base;
@tailwind components;
@tailwind utilities;

Step Five - Test Locally

Now, let's test out our configuration so far by deploying the Docusaurus site locally (default on port 3000) by running the following commands in the command line:

yarn clear
yarn start

Finally, we can test out TailwindCSS by modifying the homepage (src/pages/index.js) to replace JSX returned by the HomepageHeader function with the following:

<header className="bg-blue-500">
      <div className="container mx-auto text-center py-24">
        <h1 className="text-4xl font-bold text-white">{siteConfig.title}</h1>
        <p className="text-xl py-6 text-white">{siteConfig.tagline}</p>

        <div className="py-10">
          <Link
            className="bg-white rounded-md text-gray-500 px-4 py-2"
            to="/docs/intro"
          >
            Docusaurus Tutorial - 5min ⏱️
          </Link>
        </div>
      </div>
    </header>

Since Docusaurus supports live-reload then your local deployment (on port 3000) should refresh to display the following:

If you come across any errors or issues, feel free to reach out to me so I can help or edit this article

As previously mentioned, feel free to clone the github repo

Comments

[haobinliang]

Very useful - thank you!

Any chance that you also know how to use Tailwind CSS' dark mode instead of default?

[d-suke]

Hello haobinliang

I have found a way to make Tailwind CSS and Docusaurus dark mode coexist.
Put the following in docusaurus.config.js

module.exports = {
  themeConfig: {
    colorMode: {
      disableSwitch: true,
      respectPrefersColorScheme: true,
    },
  },
};

This allows styling with the dark utilities of Tailwind CSS.
There is a caveat, however, that you cannot manually toggle the color mode.

[Joshua Siagian]

Hi, you can update your tailwind.config.js with the following setting

module.exports = {
  darkMode: ['class', '[data-theme="dark"]'],
}

[swyx]

this was perfect. cheers

[Loïc Poullain]

It works, thanks! Adding corePlugins: { preflight: false } to tailwind.config.js will also make the native Docusaurus components to be styled as expected.

[Adrian Bienias]

Worth noting is that if you use Tailwind in md/mdx files, you should update tailwind.config.js accordingly, e.g.

module.exports = {
  content: ["./src/**/*.{js,jsx,ts,tsx,md,mdx}", "./docs/**/*.{md,mdx}"],
  // ...
}

There's also an option to disable certain Tailwind classes, e.g. container

module.exports = {
  // ...
  blocklist: ["container"],
  // ...
}

With additional improvements pointed out by @suabahasa & @loicpoullain, the final tailwind.config.js file may look like the following:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{js,jsx,ts,tsx,md,mdx}", "./docs/**/*.{md,mdx}"],
  theme: {
    extend: {},
  },
  plugins: [],
  darkMode: ["class", '[data-theme="dark"]'],
  corePlugins: {
    preflight: false,
  },
  blocklist: ["container"],
}

[Beyondr]

Yup, this is basically what I did. Thanks for the write up!

[Seraphin Vandegar]

Working perfectly with Docosorus v2. Thank you!

[Mitch Chimwemwe Chanza]

Awesome post. keep up the good work!!