Wiki

外观

一.前置准备 ​

  1. 必装：安装nodejs（推荐22及以上版本）
  2. 推荐：安装vscode
  3. 推荐：安装git
  4. 安装包管理器：pnpm / yarn / bun
bash
#安装pnpm
npm install -g pnpm
#查看版本号
pnpm -v
bash
#安装yarn
npm install -g yarn
#查看版本号
yarn -v
bash
#安装yarn
npm install -g bun
#查看版本号
bun -v

二. 正式开始 ​

1.安装vitepress ​

bash
pnpm add -D vitepress
bash
yarn add -D vitepress
bash
bun add -D vitepress
bash
npm i -D vitepress

进行下一步前可以先在指定路径创建文件夹，如：wiki。

2.初始化向导 ​

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

bash
pnpm vitepress init
bash
yarn vitepress init
bash
bun vitepress init
bash
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.

说明

点我查看

1. VitePress 应该在哪里初始化配置？（配置文件的放置位置，推荐 './docs'）

2. "VitePress 应该去哪里找的 Markdown 文件?（用来存放文章的地方，推荐'./docs'）

3. Site title 代表网站标题，后续可在配置文件中修改

4. Site description 代表网站描述，后续可在配置文件中修改

5. Theme，不想折腾选 'Default Theme'，需要自定义样式选另外两个

6. 是否使用 TypeScript 来编写配置文件和主题文件？

  • 选择Yes，使用[.mts/.ts]，TypeScript 格式，有类型提示，更规范
  • 选择No，使用[.mjs/.js]，JavaScript 格式，无类型检查，更简单

7. 是否在 package.json 中添加 VitePress 的 npm 脚本？

  • 选择Yes（推荐），自动添加 docs:dev 、 docs:build 、 docs:preview 三条脚本
  • 选择No，不添加，需要手动写

8. 是否为 VitePress 的 npm 脚本添加前缀？（默认Yes即可）

9. 输入自定义前缀的提示（8问题选择了Yes，就会进入这一步，手动输入前缀，推荐docs，vp，vitepress或直接回车）

选择TypeScript，成功安装后会有如下文件结构：

sh
.
├─ docs
│  ├─ .vitepress
│  │  └─ config.mts
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

docs 目录作为 VitePress 站点的项目根目录。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置，config.mts是配置文件。

3.脚本命令 ​

默认不用改，在 package.json 中可以查看

建议

在里面添加一个 "type": "module", ，避免有时出现未知错误

json
{
  "devDependencies": {
    "vitepress": "^1.3.4"
  },
  "packageManager": "pnpm@8.6.10+sha1.98fe2755061026799bfa30e7dc8d6d48e9c3edf0",
  "type": "module",
  "scripts": { 
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

4.git忽略项 ​

添加 .gitignore 文件，主要用于上传到 Gitee/Github 时，忽略这些文件不上传

shell
echo node_modules >> .gitignore
echo cache >> .gitignore
echo dist >> .gitignore

三. 启动 ​

本地启动开发环境

shell
pnpm run docs:dev
shell
yarn docs:dev
shell
npm run docs:dev
shell
bun run docs:dev

生成一个本地 5173 端口的链接，复制到浏览器打开进行预览

shell
F:\vitepress>pnpm run docs:dev

@ docs:dev F:\vitepress
vitepress dev docs


  vitepress v1.6.3

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

按 Ctrl+C键 即可退出开发模式