快速开始
开始之前
VitePress Blog 主要适合两类场景：
- 你准备从零开始搭一个基于 VitePress 的博客
- 你已经有一个 VitePress 站点，想把它扩展成“文档 + 博客”
如果你想先看看生成后的结构和效果，可以直接在浏览器中通过 StackBlitz 体验 VitePress Blog。
前置条件
安装依赖
VitePress Blog 既可以用于全新项目，也可以集成到已有的 VitePress 站点中。
这个主题基于 扩展默认主题 的方式构建，所以整体配置方式依然是 VitePress 那一套，你也可以继续在 docs/.vitepress/theme/index.js 中扩展站点。
先安装所需依赖：
$ npm install -D vitepress @chunge16/vitepress-blogs-theme tailwindcss @tailwindcss/vite$ pnpm add -D vitepress @chunge16/vitepress-blogs-theme tailwindcss @tailwindcss/vite$ yarn add -D vitepress @chunge16/vitepress-blogs-theme tailwindcss @tailwindcss/vite安装向导
VitePress Blog 提供了一个初始化向导，可以帮你快速生成博客所需的基础目录和配置。安装完成后，运行下面的命令启动向导：
$ npx vitepress-blog-init$ pnpm vitepress-blog-init$ yarn vitepress-blog-init向导会依次询问站点初始化所需的几个关键配置：
┌ 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)
│
◇ Default author name:
│ Blog Author
│
◇ Enable Giscus comments?
│ No
│
◇ Add VitePress npm scripts to package.json?
│ yes
│
◇ Date format:
│ yyyy/MM/dd (e.g., 2024/01/26)
│
└ Done! Now run:
pnpm install
pnpm run docs:dev确认完成后，向导会自动帮你完成这些事情：
- 在目标目录中生成博客页面、作者页面以及
.vitepress主题文件 - 当项目中不存在
package.json时自动创建一个新的配置文件 - 如果你选择允许写入脚本，会把
docs:dev、docs:build、docs:preview合并写入已有的package.json - 自动把 VitePress 缓存目录和构建产物目录追加到
.gitignore - 安全写入站点标题、描述等文本，避免因为特殊字符导致生成的配置文件出错
如果你是在已有项目中运行向导，它会保留现有的 package.json 内容，只补充缺失的 VitePress Blog 脚本。
你会得到什么
如果你将博客初始化到 ./docs，生成后的目录结构大致如下：
├── docs
│ ├── .vitepress
│ │ ├── theme
│ │ │ └── index.js
│ │ └── config.js
│ ├── blog
│ │ ├── authors
│ │ ├── posts
│ │ ├── archives.md
│ │ ├── index.md
│ │ └── tags.md
│ ├── api-examples.md
│ ├── index.md
│ ├── markdown-examples.md
│ └── public
└── package.json也就是说，向导跑完后，你拿到的不是一堆零散配置，而是一套已经把博客结构接好的 VitePress 站点。
文件结构
这套结构刻意保持得比较简单：
docs是整个 VitePress 站点的根目录.vitepress里放的是站点配置和主题入口blog/posts用来存放博客文章blog/authors用来存放作者资料页blog/index.md、tags.md、archives.md是主题内置的博客导航页面
配置文件
主题的主要配置放在 .vitepress/config.js 的 themeConfig.blog 下。
完整的主题配置项请参考 VPB 主题配置。
.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)
},
})主题入口
VitePress Blog 是在 VitePress 默认主题之上扩展出来的，所以你依然可以继续在 .vitepress/theme/index.js 中添加组件、样式或 enhanceApp 逻辑。
.vitepress/theme/index.js
import { VPBTheme } from '@chunge16/vitepress-blogs-theme'
export default {
extends: VPBTheme,
enhanceApp({ app }) {
// ...
},
}启动站点
如果你在初始化时允许向导自动修改 package.json，它会写入以下脚本：
{
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
}
}如果这些脚本已经存在，向导会保留原有内容，不会覆盖。
使用 docs:dev 即可启动本地开发服务器：
$ npm run docs:dev$ pnpm run docs:dev$ yarn docs:dev站点跑起来之后，通常下一步会是：
- 改掉默认的站点标题和描述
- 替换示例作者信息
- 在
docs/blog/posts下新增第一篇文章 - 去 VPB 主题配置 里继续调整路径、图标和日期格式