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
Top comments (9)
Very useful - thank you!
Any chance that you also know how to use Tailwind CSS' dark mode instead of default?
Hello haobinliang
I have found a way to make Tailwind CSS and Docusaurus dark mode coexist.
Put the following in docusaurus.config.js
This allows styling with the dark utilities of Tailwind CSS.
There is a caveat, however, that you cannot manually toggle the color mode.
Hi, you can update your
tailwind.config.js
with the following settingthis was perfect. cheers
It works, thanks! Adding
corePlugins: { preflight: false }
totailwind.config.js
will also make the native Docusaurus components to be styled as expected.Worth noting is that if you use Tailwind in
md/mdx
files, you should updatetailwind.config.js
accordingly, e.g.There's also an option to disable certain Tailwind classes, e.g.
container
With additional improvements pointed out by @suabahasa & @loicpoullain, the final
tailwind.config.js
file may look like the following:Yup, this is basically what I did. Thanks for the write up!
Working perfectly with Docosorus v2. Thank you!
Awesome post. keep up the good work!!