Getting Started

Before You Start

VitePress Blog works well in two common situations:

• You are starting a brand-new VitePress blog project
• You already have a VitePress site and want to add blog functionality to it

If you just want to explore the generated structure first, try the template in StackBlitz.

Prerequisites

• Node.js 18 or later
• A terminal to run the VitePress CLI
• A text editor with Markdown support
• VS Code with the official Vue extension is recommended

Install the Packages

VitePress Blog can be used in a brand-new project or added to an existing VitePress site.

The theme extends the default VitePress theme, so the setup stays familiar and you can keep customizing docs/.vitepress/theme/index.js as your site grows.

Install the required packages first:

npm

$ npm install -D vitepress @chunge16/vitepress-blogs-theme tailwindcss @tailwindcss/vite

pnpm

$ pnpm add -D vitepress @chunge16/vitepress-blogs-theme tailwindcss @tailwindcss/vite

yarn

$ yarn add -D vitepress @chunge16/vitepress-blogs-theme tailwindcss @tailwindcss/vite

Setup Wizard

VitePress Blog includes a setup wizard that scaffolds the basic blog structure for you. After installing the package, run:

npm

$ npx vitepress-blog-init

pnpm

$ pnpm vitepress-blog-init

yarn

$ yarn vitepress-blog-init

The wizard walks you through the core setup values for your site:

┌   VitePress Blog Theme Init
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Blog
│
◇  Site description:
│  A VitePress Blog with Theme
│
◇  Site base URL:
│  /
│
◇  Choose site language:
│  简体中文 (zh-CN)
│
◇  Choose starter template:
│  minimal - core blog structure only
│
◇  Default author name:
│  Blog Author
│
◇  Enable Giscus comments?
│  No
│
◇  Add VitePress npm scripts to package.json?
│  yes
│
◇  Add VitePress output entries to .gitignore?
│  Yes
│
◇  Overwrite generated files if they already exist?
│  No
│
◇  Date format:
│  yyyy/MM/dd (e.g., 2024/01/26)
│
└  Done! Next steps:

  pnpm install
  pnpm run docs:dev

After that, it will:

• Generates the blog pages, author pages, and .vitepress theme files in the target directory
• Lets you choose a minimal blog scaffold or a demo scaffold with localized example content
• Creates a new package.json when the project does not already have one
• Adds VitePress scripts for the selected target directory to an existing package.json when you choose that option
• Adds missing runtime packages to package.json without duplicating dependencies already declared elsewhere
• Appends the required VitePress cache and build output entries to .gitignore
• Safely writes text values such as titles and descriptions into the generated config files
• Stops before replacing existing generated files unless you explicitly choose overwrite

If you run the wizard inside an existing project, your current package.json is preserved and only the missing VitePress blog scripts and dependencies are added.

What You Get

If you initialize the blog in ./docs, the generated structure will look like this:

├── docs
│   ├── .vitepress
│   │   ├── theme
│   │   │   └── index.js
│   │   └── config.js
│   ├── blog
│   │   ├── authors
│   │   ├── posts
│   │   ├── archives.md
│   │   ├── index.md
│   │   └── tags.md
│   ├── index.md
│   └── public
└── package.json

This gives you a usable VitePress site with a blog section already wired in.

Choose the demo starter if you also want markdown-examples.md, api-examples.md, sample posts, and sample author pages.

File Structure

The generated structure is intentionally simple:

• docs is the root of your VitePress site
• .vitepress contains site config and theme entry files
• blog/posts is where your post content lives
• blog/authors stores author profile pages
• blog/index.md, tags.md, and archives.md are the built-in blog landing pages

Config File

Most theme-specific options live in .vitepress/config.js under themeConfig.blog.

You can find the full list of blog-specific options in VPB Theme Config.

.vitepress/config.js

import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vitepress'
import { processData } from '@chunge16/vitepress-blogs-theme/config'
import { enUS } from 'date-fns/locale'

export default defineConfig({
  title: 'VitePress',
  description: 'Just playing around.',
  themeConfig: {
    blog: {
      path: '/blog',
      title: 'Blog',
      description: 'All these articles were written by chunge!',
      defaultAuthor: 'chunge',
      categoryIcons: {
        article: 'i-[carbon--notebook]',
        tutorial: 'i-[carbon--book]',
        document: 'i-[carbon--document]',
      },
      tagIcons: {
        github: 'i-[carbon--logo-github]',
        vue: 'i-[carbon--logo-vue]',
        'web development': 'i-[carbon--development]',
        javascript: 'i-[logos--javascript]',
        html: 'i-[logos--html-5]',
      },
      dateConfig: {
        format: 'yyyy/MM/dd',
        locale: enUS,
      },
    },
  },
  vite: {
    plugins: [tailwindcss()],
    optimizeDeps: {
      exclude: ['@chunge16/vitepress-blogs-theme'],
    },
    ssr: {
      noExternal: ['@chunge16/vitepress-blogs-theme'],
    },
  },
  async transformPageData(pageData, ctx) {
    await processData(pageData, ctx)
  },
})

Theme Entry

VitePress Blog extends the default VitePress theme, so .vitepress/theme/index.js is still your place to add custom components, styles, or app enhancements.

.vitepress/theme/index.js

import { VPBTheme } from '@chunge16/vitepress-blogs-theme'

export default {
  extends: VPBTheme,
  enhanceApp({ app }) {
    // ...
  },
}

Run the Site

If you chose to let the setup wizard update package.json, it will add these scripts:

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

If those scripts already exist, the wizard leaves them unchanged.

Start the local development server with docs:dev:

npm

$ npm run docs:dev

pnpm

$ pnpm run docs:dev

yarn

$ yarn docs:dev

Once the site is running, the usual next steps are:

• update the site title and description
• replace the example author content
• add your first post in docs/blog/posts
• review VPB Theme Config for paths, icons, and date formatting