拥有个人博客是一件很酷的事情,你可以用它为自己构建知识库,作为在线笔记,或分享一些有趣的研究.
在大学时期,我使用Wordpress作为个人博客的解决方案.因为他可以不需要代码,只需要懂得一点点基础的Linux知识,将Wordpress部署到自己的服务器上就行.
Wordpress非常优秀,有非常丰富的生态,各种现成的主题可以挑选.你可以在一天内搭建好一个功能完整的商业网站,还附带完整的后台.我将WordPress作为我的博客解决方案持续使用了6年时间,它稳定且可靠,但是最后我还是决定将他换掉,因为他对于博客而言太臃肿了,或许是对我而言太臃肿了.
我一直将博客作为我的在线笔记,他只需要能够正常显示文章就行了,我并不需要账户管理,评论管理这些功能,他反而使我的网页加载变慢.我忽然意识到一点,我其实只是需要一个静态网页.
并且由于我习惯使用Markdown来记录笔记,每次发表新的博客,都需要从Markdown复制到Wordpress中,这不太利于我管理他们.
因此我开始寻找一个将Markdown文本转换成静态网页的解决方案.
幸运的是,有很多工具都能做到这个.我一开始尝试了MkDocs,他非常轻量化,安装和使用都非常简单,但是它的侧重于生成一个文档站点,而不是博客,为它自定义主题需要从零开始实现交互,我并不想在这上面花费过多的时间.
之后,我找到了VitePress,这是一个由Vue驱动的静态站点生成器.Vue是一个前端框架,这意味着如果我需要为VitePress自定义主题,只需要一点点代码,调用Vue为我们准备好的组件就行.
没错,你现在看到的这个博客,就是由VitePress构建.
好了,啰嗦了这么多,终于可以开始我们的教程环节了,请原谅我的啰嗦....
DANGER
注意: VitePress的作用是将Markdown文本转换成静态网页,如果你没有使用Markdown写文章的习惯,并不建议使用VitePress
VitePress的安装
官方网站
官方文档
https://vitepress.dev/zh/guide/what-is-vitepress
环境配置与初始化
安装Node.js 20 及以上版本
进入Node.js的官网,下载安装包,然后安装即可,这里就不过多赘述了.
安装完成后在cmd运行以下指令,如果输出版本号,那么说明你已经安装成功了.
运行.
node -v 输出.
v24.13.0 (类似这种版本号)安装VitePress
cmd运行以下指令.
npm add -D vitepress@next验证安装
自定义主题的依赖项
局域网访问
npm.cmd run docs:dev -- --host 0.0.0.0初始化一个VitePress项目
首先先进入你想要存放Vitepresss项目的路径,然后在 cmd运行以下指令.
npx vitepress init VitePress会问你几个问题,请按如下参考填写.
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Where should VitePress look for your markdown files?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◇ Theme:
│ Default Theme
│
◇ Use TypeScript for config and theme files?
│ Yes
│
◇ Add VitePress npm scripts to package.json?
│ Yes
│
◇ Add a prefix for VitePress npm scripts?
│ Yes
│
◇ Prefix for VitePress npm scripts:
│ docs
│
└ Done! Now run pnpm run docs:dev and start writing. 之后VitePress便会在目录下生成以下内容.
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.mts
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.json docs 目录作为 VitePress 站点的项目根目录。.vitepress 目录是 VitePress 配置文件、Dev服务器缓存、构建输出和可选主题自定义代码的位置.
此时你在cmd中运行如下指令,即可预览网页.
npm run docs:dev 运行成后会返回如下结果,端口不一定一样
vitepress v2.0.0-alpha.17
➜ Local: http://localhost:5174/(预览网址)
➜ Network: use --host to expose
➜ press h to show help 其中 http://localhost:5174/便是预览的网址.
在浏览器中输入以下地址,便可预览效果.
接下来便开始讲解配置文件如何修改.
配置文件
初始配置文件详解
配置文件路径./docs/.vitepress/config.mts
// 1. 从 VitePress 导入配置定义函数（提供类型提示，避免写错配置）
import { defineConfig } from 'vitepress'
// 2. 导出 VitePress 配置（固定写法，VitePress 会自动读取这个配置）
export default defineConfig({
// ============== 基础配置（网站全局设置） ==============
title: "My Awesome Project", // 网站标题（浏览器标签页 + 页面左上角标题）
description: "A VitePress Site", // 网站描述（SEO 优化，搜索引擎抓取的简介）
// ============== 主题配置（页面样式、导航、菜单） ==============
themeConfig: {
// ---------------- 顶部导航栏（页面最上方的菜单） ----------------
nav: [
{ text: 'Home', link: '/' }, // 导航文字：首页，链接：根目录
{ text: 'Examples', link: '/markdown-examples' } // 导航文字：示例，链接：markdown-examples.md
],
// ---------------- 左侧侧边栏（文档目录） ----------------
sidebar: [
{
text: 'Examples', // 侧边栏分组标题（不可点击，仅展示）
items: [ // 分组下的子菜单
{ text: 'Markdown Examples', link: '/markdown-examples' }, // 菜单1
{ text: 'Runtime API Examples', link: '/api-examples' } // 菜单2
]
}
],
// ---------------- 右上角社交链接（图标+链接） ----------------
socialLinks: [
{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }
// icon：内置图标（支持 github/twitter/gitlab 等）
// link：点击图标跳转的地址
]
}
})设置网站标题与描述
设置Nav
设置Sidebar
添加页面
设置Sociallink
修改主页内容
添加搜索功能
在themeConfig中加入如下代码,就可以开启Vitepress内置的搜索功能.
themeConfig: {
......OtherCode......
search: {
provider: 'local',
options: {
locales: {
root: {
placeholder: '搜索文档',
translations: {
button: { buttonText: '搜索' },
modal: { noResults: '暂无搜索结果' }
}
}
}
}
},
......OtherCode......
]
} 添加后效果.
添加站点图标
在themeConfig中加入如下代码,就可以指定Vitepress的站点图标.
支持本地路径和网址,如果是本地路径,则需要导入图片到对应的路径.
themeConfig: {
......OtherCode......
logo: '/logo.svg',
//如果是网络地址,则为如下所示
//logo: 'https://drawingbed.aiferu.xyz/i/2023/08/03/ly8crc.jpeg',
......OtherCode......
]
} 以下是我使用网络地址指定好对应的图标之后的效果.
添加标签页图标
与站点Logo相同,他也支持本地路径和网络路径.
注意,标签页图标设置在 export default下,而不在themeConfig下.
export default defineConfig({
......OtherCode......
head: [
['link', { rel: 'icon', href: 'https://drawingbed.aiferu.xyz/i/2023/08/03/ly8crc.jpeg' }]
],
......OtherCode......
}) 以下是我使用网络地址指定好对应的图标之后的效果.
支持数学公式
要启用它，需要安装 markdown-it-mathjax3，并在配置文件中设置markdown.math 为 true.
在cmd中运行以下指令安装 markdown-it-mathjax3.
npm add -D markdown-it-mathjax3@^4 在配置文件中添加如下代码.
export default defineConfig({
......OtherCode......
markdown: {
math: true
}
......OtherCode......
}) 之后只需要在Markdown文件中插入以下代码,便可以渲染数学公式.
$$
\pi =3.1415926
$$ 更多的Latex数学公式语法详见,也可自行搜索.
https://oi-wiki.org/tools/latex/#公式
图片懒加载
图片懒加载,即图片延迟加载.具体就是当你打开网页时,并不一次性加载所有图片,只加载当前页面能渲染到的图片,你滚动到哪里,图片才加载到哪里.
开启图片懒加载,可以加快我们的网页打开速度
通过在配置文件中将 lazyLoading 设置为 true,可以为通过Markdown 添加的每张图片启用懒加载.
export default defineConfig({
......OtherCode......
markdown: {
image: {
// 默认禁用；设置为 true 可为所有图片启用懒加载。
lazyLoading: true
}
}
......OtherCode......
})设置编译路径
默认值： ./.vitepress/dist
export default defineConfig({
......OtherCode......
outDir: '../build',
......OtherCode......
})运行指令
现在,我们来总结一下运行指令,VitePress有三个常用指令,分别是开发,编译,和预览指令.
开发指令
我们之前已经运行过这个指令了,开发指令会给我们一个预览网址,当我们修改文档或配置文件时,预览网站会同步更新.
npm run docs:dev编译指令
编译指令会将我们当前的网站进行打包,并保存到我们之前设置好的编译路径中,后续部署到网页时至需要推送这部分文件到服务器上就行.
npm run docs:build预览指令
预览指令会给我们一个预览网址,此时进入的网页,就是我们通过编译指令打包出来的网页.
npm run docs:preview 到了这里,我们已经将VitePress常用设置以及基础主题的设置讲完了,但是还没有讲到该如何用VitePress搭建博客网站.
相信你已经发现了,Vitepress的基础主题是一个为了文档设计的主题,他并不能满足我们的博客需求.
因此,下面我将会介绍一些第三方博客主题,并讲解如何安装与使用本博客对应的主题.
VitePress 的第三方主题
TeekBlog
Demo站点与使用教程
Pure
项目地址与使用教程
https://github.com/airene/vitepress-blog-pure
Demo站点
Sakura
项目地址与使用教程
https://github.com/flaribbit/vitepress-theme-sakura
Demo站点
https://flaribbit.github.io/vitepress-theme-sakura/
VitePress 使用本博客同款主题
如何安装
如何配置
添加分类
添加文章