DEV Community

Shannon Clarke
Shannon Clarke

Posted on


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. 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: [],
Enter fullscreen mode Exit fullscreen mode

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.
          return postcssOptions;
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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">
            className="bg-white rounded-md text-gray-500 px-4 py-2"
            Docusaurus Tutorial - 5min ⏱️
Enter fullscreen mode Exit fullscreen mode

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

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

Top comments (6)

haobinliang profile image

Very useful - thank you!

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

d_suke profile image

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,
Enter fullscreen mode Exit fullscreen mode

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

suabahasa profile image
Joshua Siagian

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

module.exports = {
  darkMode: ['class', '[data-theme="dark"]'],
Enter fullscreen mode Exit fullscreen mode
swyx profile image

this was perfect. cheers

beyondr profile image

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

loicpoullain profile image
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.

50 CLI Tools You Can't Live Without

The top 50 must-have CLI tools, including some scripts to help you automate the installation and updating of these tools on various systems/distros.