Styling VitePress with Tailwind

Configure Tailwind as a PostCSS plugin to use it in VitePress Markdown, JS/TS, and Vue files
Monochrome etching of three people working a manual cider press outdoors. Two turn wheels, the third is crouched under the machine. Two barrels full of apples sit on the ground in front of them, and an open barrel of cider sits on a bench under an apple tree behind them.
Cider press, XVIIth century. Engraving on copper. Attribution 4.0 International (CC BY 4.0). Source: Wellcome Collection.

VitePress is a Markdown-based static site generator. Its default theme is geared towards docs sites, but it can be used for anything. It’s currently my go-to framework when building documentation for my software projects (git-random’s site is an example).

I like to write CSS via Tailwind (more exactly, I like to write CSS via programming language-configured DOM API, I’m a long-time Tailwind user, and though I’m currently more excited about UnoCSS than Tailwind it will be a while before I’ve ported my Tailwind plugins (for example tailwindcss-fluid-font-size - also a VitePress site)).

Here’s how to combine the two.

Install dependencies

Replace <package manager> with your package manager. Works with at least bun, npm, pnpm, and yarn.

shell
<package manager> add -D autoprefixer postcss tailwindcss

Initialize Tailwind

The command depends on your package manager. Here are the four most popular as of this writing. Run only one.

shell
# bun
bunx tailwindcss init

# npm
npx tailwindcss init

# pnpm
pnpx tailwindcss init

# yarn
yarn dlx tailwindcss init

Configure PostCSS

Create the PostCSS config file, and configure it.

postcss.config.mjs
js
/** @type {import('postcss-load-config').Config} */
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

Configure Tailwind content paths

This sample code assumes VitePress is in the project root. If it’s in a subdirectory, update the paths accordingly.

tailwind.config.js
js
/** @type {import('tailwindcss').Config} */
export default {
  content: ["**/*.md", ".vitepress/theme/*.{js,ts,vue}"],
};

Add Tailwind to your custom styles

Create a custom theme, if necessary

Tip

Skip this if your VitePress site already has a custom theme (for example, if you initialized VitePress with vitepress init, and selected either “Default Theme + Customization” or “Custom Theme”).

  1. Create a file .vitepress/theme/index.js or .vitepress/theme/index.ts. The latest official recommendation as of this writing is [1]

    TypeScript:

    .vitepress/theme/index.ts
    ts
    // https://vitepress.dev/guide/custom-theme
import { h } from "vue";
import type { Theme } from "vitepress";
import DefaultTheme from "vitepress/theme";
import "./style.css";

export default {
  extends: DefaultTheme,
  Layout: () => {
    return h(DefaultTheme.Layout, null, {
      // https://vitepress.dev/guide/extending-default-theme#layout-slots
    });
  },
  enhanceApp({ app, router, siteData }) {
    // ...
  },
} satisfies Theme;

    or JavaScript:

    .vitepress/theme/index.js
    js
    // https://vitepress.dev/guide/custom-theme
import { h } from "vue";
import DefaultTheme from "vitepress/theme";
import "./style.css";

/** @type {import('vitepress').Theme} */
export default {
  extends: DefaultTheme,
  Layout: () => {
    return h(DefaultTheme.Layout, null, {
      // https://vitepress.dev/guide/extending-default-theme#layout-slots
    });
  },
  enhanceApp({ app, router, siteData }) {
    // ...
  },
};

  2. Create the file .vitepress/theme/style.css.

Add Tailwind directives to the VitePress theme stylesheet

.vitepress/theme/style.css
css
@tailwindcss base;
@tailwindcss components;
@tailwindcss utilities;

Write some Tailwind

Now you can use Tailwind in Markdown page source

index.md
md
This is black.

<span class="text-red-400">This is red</span>.

and/or in VitePress theme files

.vitepress/theme/MyComponent.vue
vue
<template>Hello <span class="text-red-400">world</span>.</template>

Footnotes

  1. https://github.com/vuejs/vitepress/blob/v1.4.1/template/.vitepress/theme/index.js ↩︎

Also In This Series

Articles You Might Enjoy

Or Go To All Articles