使用VitePress从0开始搭建博客

本文旨在记录一个菜狗准备构建一个简单的博客站的辛酸过程

首先是技术选型, 我们尽量是选择一个成熟的博客框架, 不建议自己手搓. 考虑到访问速度问题, 最好是纯静态网页

经简单查阅, 静态网页生成器的框架有很多, 比如: hexo, hugo, vitepress等, 这些框架可以将你所书写的markdown文档, 编译成为静态页面. 从而避免了从一开始造轮子的艰难

这里我选择使用VitePress框架, 因为它看起来比较简约

安装

前置准备

• Node.js 18 及以上版本。具体可以搜索Windows安装NodeJS
• 通过命令行界面 (CLI) 访问 VitePress 的终端。
• 支持Markdown语法的编辑器。
• 推荐 VSCode 及其官方 Vue 扩展。

开始安装

VitePress 可以单独使用，也可以安装到现有项目中。在一个空文件夹终端输入:

npm add -D vitepress

安装向导

VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导：

npx vitepress init

将需要回答几个简单的问题：

┌  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.

如果打算使用 Vue 组件或 API 进行自定义，还应该明确地将 vue 安装为 dependency。

安装完成

输入npm run docs:dev启动即可预览默认站点

文件结构说明

• 如果正在构建一个独立的VitePress站点, 可以在当前目录(./)中搭建站点. 如果在现有项目中与其他源代码一起安装VItePress, 建议将站点搭建在嵌套目录(例如./docs)中, 以便它与项目的其余部分分开

• 假设在./docs中搭建VitePress项目, 生成的文件结构应该是这样的:

  .
  ├─ docs # 项目根目录
  │  ├─ .vitepress # 配置文件自定义代码等
  │  │  └─ config.js # 配置文件
  │  ├─ api-examples.md # 示例文档
  │  ├─ markdown-examples.md # 示例文档
  │  └─ index.md # 首页
  └─ package.json

• docs目录作为VitePress站点的项目根目录存在

• 默认情况下，VitePress 将其开发服务器缓存存储在 .vitepress/cache 中，并将生产构建输出存储在 .vitepress/dist 中。如果使用 Git，应该将它们添加到 .gitignore 文件中。也可以手动配置这些位置。

• 凡是.vitepress目录之外的md文件, 都被视为源文件