[Part 1] Setup a working Vuepress blog with Tailwind.css

In this part, we will setup a working Vuepress blog with Tailwind.css.

1. Getting Started

Let's create a folder called vuepress-blog then run these commands.

# cd into the folder
cd vuepress-blog

# install the latest vuepress alpha globally on your computer
npm install -g vuepress@next

# create the first markdown file
echo '# Hello VuePress' > README.md

# start the site locally
vuepress dev

When you run vuepress build, the README.md at the root level will be generated into index.html. Now head to localhost:8080, you should see a default site like this. Horay!!

Notice that some css already been applied to the page without any work (What's this magic ?! 😱). It's coming straight from the default theme packed in Vuepress. To alter it, run vuepress eject and a generated .vuepress folder will show up in your directory tree. It contains all the code for the default theme. We will go over this later when we start making a custom theme.

2. The correct directory structure

On the documentation, Vuepress recommends putting everything under a docs folder. You can name it with anything, but the important thing is that when running Vuepress commands, you'd need to run vuepress dev [folder name, i.e. docs] or you will see a 404 page.

On the other hand, you could simply leave everything at the root level under vuepress-blog. In this case, you just have to run vuepress dev like before.

3. Add tailwind.css

Since we don't have package.json yet, let's npm init the project first.

npm init

Then install tailwind

npm install tailwindcss

Now we are ready to generate the tailwind config

npx tailwind init tailwind.config.js

By now, your directory structure should look like this

vuepress-blog
├── node_modules
├── README.md
├── package-lock.json
├── package.json
└── tailwind.config.js

Next, we are going to create a custom theme that utilize tailwind.

4. Create a Custom Vuepress theme

At the root level of your project, create a .vuepress folder with a theme folder inside. Then inside of theme, create a styles folder. .vuepress houses everything, including your current theme and the vuepress config; the theme and styles folder is to override the default theme.

mkdir -p .vuepress/theme/styles

Now add a theme.styl in the styles folder to serve as the entry point of all css. Your directory tree should look like this:

vuepress-blog
├── .vuepress
│   └── theme
│       └── styles
│           └── theme.styl
├── node_modules
├── README.md
├── package-lock.json
├── package.json
└── tailwind.config.js

Add these lines to theme.styl to load all of our tailwind's styles.

@tailwind preflight;
@tailwind components;
@tailwind utilities;

Nice -- We are almost done!
Now we are going to tell Vuepress to connect to our tailwind. Create a file called config.js in .vuepress and put in these settings

module.exports = {
  title: "Vuepress Blog Example",
  description: "just another blog",
  postcss: {
    plugins: [
      require("tailwindcss")("./tailwind.config.js"),
      require("autoprefixer"),
    ],
  },
}

Lastly, we are going to add our theme index file. Create another folder named layouts in theme with a Layout.vue inside.

In Layout.vue let's add the very basic template for now

<template>
  <div>
    <h1 class="font-sans text-teal">hello world</h1>
  </div>
</template>
<style lang="stylus">
@import '../styles/theme.styl';
</style>

This Layout.vue will serve as the base layout of all your pages. If there is no layout specified in the frontmatter of a page, Vuepress will default to this layouts/Layout.vue. It's a required file for any vuepress theme.

Note: If your theme is super simple and doesn't have a layouts folder, you can leave the Layout.vue file directely under the theme.

Your final directory structure should look like this

vuepress-blog
├── .vuepress
│   ├── theme
│   │   └── layouts
│   │       └── Layout.vue
│   │   └── styles
│   │       └── theme.styl
│   └── config.js
├── node_modules
├── README.md
├── package-lock.json
├── package.json
└── tailwind.config.js

Restart your server now and run vuepress dev, you should see a page like this:

Make sure the tailwind classes are working (i.e. you should see the text being green instead of black.)

Nice job! By now, we have created a custom Vuepress theme that utilizes tailwind.css. In the next part, we are going to learn how to write your own theme and make your blog look awesome! Part 2 is here.

This is a cross-post from my website. Check out the original and more there!