New Tailwind theme

[jaredpalmer]

💥 Proposal

This may be belong in the Infima repo, but I strongly suggest Docusaurus consider Tailwind. Tailwind already solves for theming out of the box. It also gives developers much more freedom. You can still re-implement Infima's core classes with tailwind, so this actually wouldn't need to be a breaking change.

The benefits:

• Smaller CSS footprint
• Better theming
• Less custom CSS needed on other pages

Next Steps

• Start on a new Tailwind preset
• Get it to feature-parity with classic theme

Have you read the Contributing Guidelines on issues?

Yes

[slorber]

Hi,

I'm not very familar with Tailwind yet.

Currently Infima is a css lib with a few postcss. But it also includes some lightweight vanilla JS components

If I understand correctly, you mean we could implement current Infima CSS classes as a Tailwind preset, instead of the existing css/postcss ?

So we would publish that preset and enable users to extend / customize it more easily?

---

I see the value of Tailwind, and a similar goal of styling co-located to the markup.

Its scope is larger than current Infima:

• People having complex D2 sites will probably need additional one-of CSS styles that's not provided by Infima (afaik it also happens to Tailwind users). Atomic/utility CSS will grow slower than hand-made CSS.
• There are also simple D2 sites that do not require additional styles. Can we use Tailwind without adding unnecessary CSS to these sites?

[jaredpalmer]

Yes you can and should always purge unused tailwind css. Only the classes actually used in the codebase are kept.

[kvnxiao]

Hoping this is helpful information, as I got TailwindCSS v2 to properly work with the PostCSS config that Docusaurus v2 already uses.

I'm using a custom configureWebpack plugin in a file plugins/my-loaders/index.js like so:

module.exports = function (context, options) {
  return {
    name: 'postcss-tailwindcss-loader',
    configureWebpack(config, isServer, utils) {
      return {
        module: {
          rules: [
            {
              test: /\.css$/,
              use: [
                {
                  loader: require.resolve('postcss-loader'),
                  options: {
                    ident: 'postcss',
                    plugins: () => [
                      require('postcss-import'),
                      require('tailwindcss'),
                      require('postcss-preset-env')({
                        autoprefixer: {
                          flexbox: 'no-2009',
                        },
                        stage: 4,
                      }),
                    ],
                  },
                },
              ],
            },
          ],
        },
      }
    },
  }
}

with package.json referencing a local module dependency "my-loaders": "file:plugins/my-loaders", and docusaurus.config.js plugins entry set up as plugins: ['my-loaders'],

And a tailwind.config.js like so:

module.exports = {
  purge: ['./src/**/*.html', './src/**/*.js', './src/**/*.tsx'],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

A reference commit summarizing the above info: Discord4J/documentation@2019279

Note that the PostCSS version in which Docusaurus v2 currently uses is 7.0.XX, while the latest version of PostCSS is 8.0.X and TailwindCSS v2 by default uses PostCSS V8. I had to use a v7 compatibility install of TailwindCSS v2 for this to all work: "tailwindcss": "npm:@tailwindcss/postcss7-compat" in package.json dependencies.

I'm thinking that maybe tailwindcss can be added directly to the https://github.com/facebook/docusaurus/blob/master/packages/docusaurus/src/webpack/utils.ts#L64-L71 plugin block for getStyleLoaders with PurgeCSS configured for first class support. Since tailwindcss has PurgeCSS enabled, users who don't use tailwindcss will never see it or even know because all the tailwindcss related css rules will be removed. And there should be no performance penalties in terms of time spent compiling for users who don't import tailwindcss into their .css files or index.js/index.tsx.

---

EDIT: With the newer versions of Docusaurus v2 supporting a configurePostCss option in a plugin, the above code snippet should be changed to the following:

module.exports = function (context, options) {
  return {
    name: 'postcss-tailwindcss-loader',
    configurePostCss(postcssOptions) {
      postcssOptions.plugins.push(
        require('postcss-import'),
        require('tailwindcss'),
        require('postcss-preset-env')({
          autoprefixer: {
            flexbox: 'no-2009',
          },
          stage: 4,
        }),
      )
      return postcssOptions
    },
  }
}

[slorber]

Thanks for these infos.

We'll look at this more in depth soon, as we'll work on our theme gallery (#3522) and Tailwind support is part of it

[clairefro]

@kvnxiao I tried your config for tailwind and can't seem to get past this error (looks like it's still looking for postcss 8):

Error: Cannot find module 'postcss-import'

Do you have a working repo I could take a look at?

[kvnxiao]

@clairefro https://github.com/Discord4J/documentation

You will need to install postcss-import

[nahtnam]

@kvnxiao's solution is great! I just want to add an improvement to it. If you add the following to your tailwind.config.js: important: '#tailwind', then it will not affect the docusaurus pages. Then all you need to do is add <div id="tailwind"> around the pages that you want to use tailwind on!

[wibed]

@kvnxiao
according to postcss/postcss-import#435
postcss-import@^12 (current ^14) is based on postcss8

also the install guide on tailwindcss does not mention the postcss-import module
https://tailwindcss.com/docs/installation#post-css-7-compatibility-build

why did you made it a dependency on your module?

[kvnxiao]

@wibed This is if you want to have build time imports: https://tailwindcss.com/docs/using-with-preprocessors#build-time-imports It's not a requirement but I enabled it in case I take advantage of it. It's also build time processing so it doesn't affect the output size regardless of whether it's included or not. You may remove the require('postcss-import'), clause from the plugin excerpt I listed above previously if you don't want it.

[slorber]

FYI the next release will have a configurePostCss lifecycle, can be useful for Tailwind until we have first-class support
#4185

[theankurkedia]

@nahtnam The one with tailwind.config.js: important: '#tailwind' did not prevent default styles for other docusaurus pages. It was still overriding the default html styles. I tried tailwind.config.js: corePlugins: { preflight: false}, important: '#tailwind' and it worked for me.

[Romstar]

FYI the next release will have a configurePostCss lifecycle, can be useful for Tailwind until we have first-class support
#4185

Any idea on a timeline for first-class support?

[slorber]

@Romstar no timeline to be defined, as it requires a significant amount of refactoring work to avoid duplicating everything between the themes. It's not a short term priority but more mid-term.

[jquense]

@slorber if someone wanted a tailwind theme now-ish, would you suggest waiting a bit more, or plowing ahead and making their own (knowing the work will be obsoleted eventually). Is it still a mid term goal? It seems like abstracting common logic from themes, is a fairly significant undertaking and likely requires some rethinking of how themes work?

[slorber]

@jquense I think you'd better implement that theme yourself for now, and we may be able to benefit from this third-party implementation once Docusaurus has refactored its theme system.

The goal is to share the same UX across all the official themes, and just have to implement the UI / head / styled components for each theme. We should also try to make it so that theme refactors are less likely to break sites of users that have implemented a custom theme or swizzled a component. I don't like too much the way swizzling works currently, as it creates a quite implicit API surface for which it's hard to be retrocompatible, so yeah it requires a decent amount of work to prepare all that.

The goal is not just to have a Tailwind theme: it's also to make sure that it's easy to maintain, does not break and stays in sync with the classic theme over time.

We have seen what happens to the "bootstrap" theme over time. As there's currently a lot of code duplication, it became unmaintained and a burden and is now in a very bad state. If we have a Tailwind theme, we don't want that to happen.

[Romstar]

@kvnxiao's solution is great! I just want to add an improvement to it. If you add the following to your tailwind.config.js: important: '#tailwind', then it will not affect the docusaurus pages. Then all you need to do is add <div id="tailwind"> around the pages that you want to use tailwind on!

Actually, can you try this: // tailwind.config.js
module.exports = {
prefix: 'tw-',
}

The prefix solved the collision issue for me.

[LunaticMuch]

I can say the same here. Right now my company is looking at docusaurus but the way css are managed is not nice. You can't go with tailwind and align the UX to the rest of the standard if you use the default classic theme.
Otherwise you need to build own theme and it's an effort.

[aersosi]

@jquense

Hey there, I would be happy to help. I've seen your last commits in the "docusaurus-theme-tailwind" are monts ago.
Of course, I'm interested in using tailwind for my own docusaurus projects. 👯

[slorber]

Note the classic theme is under serious refactorings to create smaller fine-grained and encapsulated components, and move the technical code (non-coupled to Infima) to the @docusaurus/theme-common package.

• refactor(theme-classic): split sidebar into smaller parts #6844
• refactor(theme-classic): split theme footer into smaller components + swizzle config #6894
• refactor(theme-{classic,common}): split navbar into smaller components + cleanup + swizzle config #6895
• other PRs to come

I'd suggest waiting for these refactorings to be completed before investing too much time in a third-party Tailwind theme. (although we might be able to copy/paste some existing markup when we are ready)

We'll likely also provide some useful tooling so that all themes that want to provide the same layout/UX as the classic theme can stay in sync and keep the same file-system structure, as the main difference should be the UI/CSS, not the component API surface

[jquense]

I am happy to wait it out. it's been to much work to keep it up compared to what i save using it :P

[aersosi]

@slorber
Just a quick question out of curiosity.
Do you have a timeline for the TW theme, or is it more like "it's done when it's done"?

Kind regards

[slorber]

it's done when it's done

We are continuously extracting technical / non-ui code from the classic theme so that producing a new Tailwind does not lead to a ton of duplication.

Unfortunately, it's hard to estimate. We'll first cleanup the theme to make it easier to customize, release 2.0 asap, and only then start working on this new official Tailwind theme.

And as part of an open-source project, there is also general maintenance work, community PRs and other quality of life improvements to ship so it's hard to dedicate 100% of the efforts to this single project. But it is definitively something that we try to slowly make happen in the background

[PoetaKodu]

I strongly advise making Tailwind optional.

[CodeFromAnywhere]

I don't know if anyone has the same problem, but for me the tailwind installation had lead to the whole site being ugly. After a lot of searching I found that simply disabling preflight solves it because it doesn't change the html defaults.

You can add this in your tailwind.config.json

 corePlugins: {
    preflight: false,
  }

[LunaticMuch]

I don't know if anyone has the same problem, but for me the tailwind installation had lead to the whole site being ugly. After a lot of searching I found that simply disabling preflight solves it because it doesn't change the html defaults.

You can add this in your tailwind.config.json

 corePlugins: {

    preflight: false,

  }

How did you import tailwind?

[paularmstrong]

Is there an umbrella task or list somewhere for the work to extract logic out of the classic theme and into theme-common to help out on making more themes possible?

[slorber]

No umbrella issue but you could look at theme components and see if there is some code that is technical and not really related to theming/styles/CSS. Sometimes it's hard to extract, but there are still a few low-hanging fruits that contributors can help moving ;)

[andreipope]

Hey @slorber ,

We love Docusaurus, and we're building our documentation website on top of it. We're also looking at using Tailwind, so I'm just wondering if you could shed some light on when the Tailwind theme will be available. I understand that you don't have an ETA, but it would be helpful to know whether it'll take weeks, months, or maybe even more. We're not sure if we'd be better off implementing the key features now and wait for the new theme to be ready before we polish the website or if we should just hack our way through the existing codebase and get all the features implemented on top of the existing classic theme. The main concern is that we have to swizzle a large number of components, and this could cause issues when upgrading our version of Docusaurus.

Thank you,
Andrei.

[slorber]

Hey, I'm sorry but I have limited bandwidth, only work on Docusaurus 3d/week, also take holidays, have to spend like 50% of my time doing support and answering issues (like this one).

In conclusion, I have not much more than 1d/week to work on ambitious features for Docusaurus, and it's hard for me to tell you how much time it will take considering there are more urgent things to handle such as migrating to React 18, MDX 2.0, ESM, fixing important bugs, DX issues and pending PRs to reviews.

So no, I really can't answer you on when a Tailwind theme will land, nor what decision you should make.

Please assume it will take time, and that you should rather take a decision based on the current state of Docusaurus instead of waiting for official support.

If you really want Docusaurus with Tailwind support today, it remains possible to implement in userland, as @jquense did in his POC above. And doing so will help us: once the time comes, we'll be able to copy your existing JSX+className markup to create the official version. For sure it requires a lot of effort to create it and keep it on par with the existing classic theme, but it is definitively possible.

Note that you can still contribute to our opencollective if you want to give us more bandwidth to implement things faster.

[andreipope]

Hi,

We appreciate you taking the time to answer our question. We just wanted to get more insight into this. Thanks for sharing all the useful information!

Best,
Andrei.

[gazpachu]

 corePlugins: {
    preflight: false,
  }

In my team, we prefer to keep the preflight styles but, in order to avoid collisions with Docusaurus styles, we need to load @tailwind base; earlier than the Docusaurus styles.

Unfortunately, if we add @tailwind base; to the top of the src/css/custom.css file, the TW preflight styles load after the Docusaurus styles. That's what causes the issue with the UI getting borked and the need to disable the preflight.

So, is there any other file we could use to load @tailwind base; earlier? I guess not?

@slorber I think one solution would be to make Docusaurus a headless documentation lib. In that way, everyone could choose their preferred CSS architecture to style the UI. Or keep infima for the default CSS architecture but allow users to completely remove it easily.

[slorber]

@slorber I think one solution would be to make Docusaurus a headless documentation lib

That's already the direction we take by moving most client code not related to styling to a @docusaurus/theme-common package, but there's still a lot of work to do to make it happen.

Or keep infima for the default CSS architecture but allow users to completely remove it easily.

It is already possible to implement your own theme, not using Infima. The problem is that you'll have to reimplement many things. The goal of @docusaurus/theme-common is that you'll have to only have to reimplement the things related to styling, and reuse all the things we already worked on for the classic theme (theme config, React hooks, accessibility, i18n, UX...).

---

I can't help much on the Tailwind side, I don't have much experience using it so far.

[jcstein]

Is it possible to apply styling to only one page? I'm working on this use-case in this PR

[KoenRijpstra]

@gazpachu I found a workaround for loading the preflight before the Docusaurus styles. I disabled preflight in the tailwind.config.js and then Injected the preflight CSS with the injectHtmlTags option:

async function pluginTailwindCSS(context, options) {
  return {
    name: "docusaurus-tailwindcss",
    injectHtmlTags() {
      return {
        headTags: [
          {
            tagName: "link",
            attributes: {
              rel: "stylesheet",
              href: "https://cdn.jsdelivr.net/npm/tailwindcss/dist/preflight.min.css",
            },
          },
        ],
      };
    },
    configurePostCss(postcssOptions) {
      // Appends TailwindCSS and AutoPrefixer.
      postcssOptions.plugins.push(require("tailwindcss"));
      postcssOptions.plugins.push(require("autoprefixer"));
      return postcssOptions;
    },
  };
},