VitePress is fun!

You might be considering next platform for your blog or personal website and I think you will love VitePress. Let me explain why...

Basic idea

In my opinion VitePress is great if you want to write posts or content in general in Markdown and have it magically transformed into nice looking HTML.

It doesn't have an admin panel like you have in Wordpress. It doesn't have any automation or editor where you write your posts. Basically, you write your posts in text editor of your choice and you use Markdown to style it.

The final output are HTML files that you can upload to any web server that can handle static pages and you're ready to present it to the world!

Installation

VitePress can be installed on its own or can be added to existing project. It requires Node.js 18.x or greater. Let's start from beginning:

1. Open your terminal/console app (I'm using iTerm2 but also hear a lot of good things about Hyper).

2. Create an empty folder where your VitePress website will exist, for example execute command mkdir ~/code/vitepress

3. Switch your current folder to the newly created one cd ~/code/vitepress

4. Install VitePress as you dev dependency npm install -D vitepress

5. Now let's start the installer npx vitepress init. It will ask you few questions:

   • "Where should VitePress initialize the config?" - press Enter to install in current folder or specify relative path.
   • "Site title" - give your site a name.
   • "Site description" - write short description of your site.
   • "Theme" - select theme that you want to use. For now let's choose "Default Theme".
   • "Use TypeScript for config and theme files?" - here I always answer "Yes" but standard Javascript will be also fine. Choose as you like.
   • "Add VitePress npm scripts to package.json?" - let's answer "Yes" to have VitePress install its scripts in package.json file.
   • All done!

6. Now you should be able to run npm run docs:dev in the folder where your VitePress is installed and you should see your default VitePress website in browser at localhost:5173

Configuration

Configuration will depend on your needs and your ideas. I will show you what I usually do.

Syntax highlighting for *.mts files

You probably noticed that if you tell VitePress to use TypeScript, you will find files with mts extension in project folders. My Sublime Text didn't know how to highlight syntax in these files, so I opened one of mts files and went to top menu: View > Syntax > Open all with current extension as... > JavaScript > TypeScript

Change source directory

By default VitePress is using root folder to store its source Markdown files. I like to have them in src folder to better understand where's my source and then where's my output.

To make Vitepress look for source files in src folder, edit .vitepress/config.mts file and add one line:

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  srcDir: 'src', 
  title: [...]

You can now move all Markdown files (*.md) from root folder into new src folder and run npm run docs:dev to make sure it's still working as before and you can see the same pages in browser.

Lock NPM and NodeJS version

I'm using NVM to manage different versions of NPM and NodeJS on my laptop. It's easy to switch from one version to another and I've got a lot of projects. My shell is set to switch automatically when it find .nvmrc file in folder. It's also useful file if you are using NVM because simple command like nvm use will switch you to the NPM version that's used within a project. Content of .nvmrc is version number or name, so it can be just 19.

So, make sure you are in your VitePress project's folder cd ~/code/vitepress and create new file .nvmrc (dot at the beginning of file's name) and inside this file put just 19. Save file. Done!

Now do nvm use to switch Node and NPM to version 19. If you don't have it installed, then follow the information on your screen.

Install code validation and code formatting tools

I admit this is not so important in VitePress project because you won't be writing so much code, but when you do, it is good to have your editor format everything on save and use some coding standards.

I'm always using Eslint and Prettier to validate my code and to make it look good and follow some styling guidelines. To install the, run

npm install -D @antfu/eslint-config eslint eslint-plugin-vue prettier

Now we need to create two new files in the main folder of your VitePress project (cd ~/code/vitepress):

• .eslintrc with content:

{
    "extends": "@antfu",
    "rules": {
        "curly": ["error", "multi-line"],
        "no-console": "off"
    }
}

• .prettierrc.json with content:

{
  "semi": false,
  "singleQuote": true
}

Setting up your code editor is for another time, but just for reference - if you are using Sublime Text 4 as I do, I had to disable formatting of Markdown files in my JsPrettier extension so I edited its settings and added:

"auto_format_on_save_excludes": [
    "*.md"
]

TailwindCSS

I'm a big fan of TailwindCSS and I just cannot see a project without it, so I wanted it in VitePress as well! It's quite simple to add, so let's do it!

In VitePress project folder run npm install -D postcss tailwindcss autoprefixer to install all TailwindCSS dependencies as dev dependencies.

Now create TailwindCSS config file: npx tailwindcss init. It will appear in root folder in your project. It's an empty config file at the moment.

Let's point TailwindCSS to the VitePress files for processing. Add one line to tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.md', 
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

We also have to edit package.json file which sits in the root folder of your VitePress project. At the end of this file, just before last closing bracket add:

"postcss": {
  "plugins": {
    "tailwindcss": {},
    "autoprefixer": {}
  }
}

Now we need to extend default template and inject TailwindCSS stylesheet, so create new folder under .vitepress folder, called theme and inside it create file index.ts.

Edit this file (full path is .vitepress/theme/index.ts) and write:

import DefaultTheme from 'vitepress/theme'
import './tailwind.pcss'

export default DefaultTheme

In the same folder create tailwind.pcss file (PCSS extension is for PostCSS files). Inside this file (full path .vitepress/theme/tailwind.pcss) write:

@tailwind base;
@tailwind components;
@tailwind utilities;

TailwindCSS is now ready for your code! Go into your src folder and edit any Markdown file to test it. I would edit src/index.md file and add this line at the end of the file:

<p class="inline-block m-4 px-8 py-4 border-4 border-amber-500 rounded-xl text-green-600 bg-white">TailwindCSS is amazing!</p>

Just don't place this code inside --- block because that's treated as data block.

That's it for now! I'll write more in part two. Now go and write some Markdown!

COMMENTS