心流笔记

主题

Wilson2025-03-06 07:59:25指南指南
1354
6.5m

快速开始 ​

版本 ​

Teek badge

Vitepress 安装 ​

有关 Vitepress 的安装教程来源于 VitePress 文档。如果安装失败，请阅读 Vitepress 文档查看最新的安装教程。

sh
pnpm add -D vitepress
sh
yarn add -D vitepress
sh
npm add -D vitepress

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

sh
pnpm vitepress init
sh
yarn vitepress init
sh
npx vitepress init

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

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

Teek 在线安装 ​

建议使用如下包管理器安装 vitepress-theme-teek：

sh
pnpm install vitepress-theme-teek -D
sh
yarn add vitepress-theme-teek -D
sh
npm install vitepress-theme-teek -D

Teek 引入 ​

根据 Vitepress 的要求，需要在 .vitepress/theme/index.ts 文件中引入 Teek 主题。如果没有该路径，需要先创建它：

ts
import Teek from "vitepress-theme-teek";
import "vitepress-theme-teek/index.css";

export default {
  extends: Teek,
};

然后在 .vitepress/config.ts 文件中引入 Teek 的配置信息：

ts
// .vitepress/config.ts
import { defineConfig } from "vitepress";
import { defineTeekConfig } from "vitepress-theme-teek/config";

// Teek 主题配置
const teekConfig = defineTeekConfig({});

// Vitepress 配置
export default defineConfig({
  extends: teekConfig,
  // ...
});

有关 Teek 更多的配置信息，请从 配置简介 开始阅读。

启动运行 ​

请查看你的 package.json 文件，确保存在下面 npm 脚本：

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

docs:dev 脚本将启动具有即时热更新的本地开发服务器。使用以下命令运行它：

sh
pnpm run docs:dev
sh
yarn docs:dev
sh
npm run docs:dev

vitepress dev docs 的 docs 并不是固定写死的，有三种场景可以进行选择：

  • 如果 .vitepress 和 Markdown 文档在项目根目录下，则 vitepress dev docs 改为 vitepress dev
  • 如果 .vitepress 和 Markdown 文档在项目 src 目录下，则 vitepress dev docs 改为 vitepress dev src
  • 如果 .vitepress 在项目根目录下，Markdown 文档放在 src 目录下，则 vitepress dev docs 改为 vitepress dev，且需要在 .vitepress/config.ts 里配置 srcDir: src，srcDir 的作用请看 Vitepress - srcDir

总结：Vitepress 以 .vitepress 所在的目录层级 + srcDir 为参照逐层对 Markdown 文档扫描解析。

Teek 本地安装（可选） ​

Teek 本地安装和 Teek 在线安装需要二选一。虽然可以同时安装，但是最终引入 Teek 的时候只能选择 1 个。

本地安装分为 文件夹引入 和 monorepo 安装，这里仅介绍 文件夹引入 的方式，如果你打算使用 monorepo 安装，说明您已经有一定的技术经验，那么可以参考 Teek 本身的 monorepo 架构去实现本地安装。

Teek 本地安装需要将 Teek 源代码下载到本地，然后在项目中引入。

sh
git clone https://github.com/Kele-Bingtang/vitepress-theme-teek.git

如果 GitHub 克隆速度较慢，你也可以直接克隆 Gitee 上的镜像仓库，同步可能会存在时差。

sh
git clone https://gitee.com/kele-bingtang/vitepress-theme-teek.git

Teek 的有较多的开发文件，您只需要将 vitepress-theme-teek/src 复制到自己的项目里，并将 src 更名为 teek，假设复制到了 .vitepress/theme 目录：

.
├─ .vitepress
│  ├─ theme
│  │  ├─ teek （等于 vitepress-theme-teek/src 目录）
│  │  ├─ index.ts
│  ├─ config.ts

您需要安装 Teek 运行必备的依赖（可以直接查看 vitepress-theme-teek/package.json 文件）。

sh
pnpm add gray-matter js-yaml markdown-it-container -D
pnpm add @types/js-yaml @types/markdown-it @types/markdown-it-container -D

pnpm add vitepress-plugin-auto-frontmatter
pnpm add vitepress-plugin-catalogue
pnpm add vitepress-plugin-doc-analysis
pnpm add vitepress-plugin-file-content-loader
pnpm add vitepress-plugin-md-h1
pnpm add vitepress-plugin-permalink
pnpm add vitepress-plugin-sidebar-resolve

pnpm add element-plus sass -D
sh
yarn add gray-matter js-yaml markdown-it-container -D
yarn add @types/js-yaml @types/markdown-it @types/markdown-it-container -D

yarn add vitepress-plugin-auto-frontmatter
yarn add vitepress-plugin-catalogue
yarn add vitepress-plugin-doc-analysis
yarn add vitepress-plugin-file-content-loader
yarn add vitepress-plugin-md-h1
yarn add vitepress-plugin-permalink
yarn add vitepress-plugin-sidebar-resolve

yarn add element-plus sass -D
sh
npm add gray-matter js-yaml markdown-it-container -D
npm add @types/js-yaml @types/markdown-it @types/markdown-it-container -D

npm add vitepress-plugin-auto-frontmatter
npm add vitepress-plugin-catalogue
npm add vitepress-plugin-doc-analysis
npm add vitepress-plugin-file-content-loader
npm add vitepress-plugin-md-h1
npm add vitepress-plugin-permalink
npm add vitepress-plugin-sidebar-resolve

npm add element-plus sass -D

然后在 .vitepress/theme/index.ts 文件中引入 Teek：

ts
import Teek from "./teek";

export default {
  extends: Teek,
};

最后在 .vitepress/config.ts 文件中引入 Teek 的配置信息：

ts
// .vitepress/config.ts
import { defineConfig } from "vitepress";
import { defineTeekConfig } from "./theme/teek/config";

// Teek 主题配置
const teekConfig = defineTeekConfig({});

// Vitepress 配置
export default defineConfig({
  extends: teekConfig,
  // ...
});

在线与本地区别 ​

如果想要基于 Teek 二次开发，自定义自己的风格，那么请采用本地安装方式。

Teek 不定期提供新特性或者修复 Bug，如果想要及时享用，那么请采用在线安装方式，届时只需要更新版本即可：

sh
pnpm add vitepress-theme-teek@latest -D
sh
yarn add vitepress-theme-teek@latest -D
sh
npm add vitepress-theme-teek@latest -D
最近更新