VitePress1.0正式版终于发布啦！[Announcing VitePress 1.0 | The Vue Point (vuejs.org)](https://blog.vuejs.org/posts/vitepress-1.0) 一年多来，从测试版开始，就用VitePress来写博客文档，写了最大的一个文档打包后有500多MB大小，下面是我使用VitePress写博客和部署的一些经验和总结，文后附上示例博客文档，可以直接克隆下来写并部署自己的静态文档博客。 ## VitePress相关网址开源地址：官网文档： ## VitePress 是什么？ VitePress 是一个[静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG)，专为构建快速、以内容为中心的站点而设计。简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。 **下面是我使用 VitePress 写博客文档和部署的一些经验和总结** ## VitePress 安装和使用安装文档：[快速开始 | VitePress](https://vitepress.dev/zh/guide/getting-started) ### 1.新建一个项目目录 #### 1.1 新建一个博客文档的项目目录：如mydoc ### 2. VSCode打开该目录，然后运行终端 #### 1.2.1 初始化项目 ```bash npm init ``` #### 1.2.2 安装vitepress ```bash pnpm add -D vitepress ``` #### 1.2.3 初始化vitepress项目向导 ```bash pnpm vitepress init ``` 将需要回答几个简单的问题：以下是按照官网文档选择 ```bash ┌ Welcome to VitePress! │ ◇ Where should VitePress initialize the config?（vitepress主要文件夹） │ ./docs │ ◇ Site title:（站点标签的标题） │ My Awesome Project │ ◇ Site description:（站点主页的描述） │ A VitePress Site │ ◆ Theme:（可选的主题。这里我选第二个：默认的主题+可定制的） │ ○ Default Theme (Out of the box, good-looking docs) │ ● Default Theme + Customization │ ○ Custom Theme ``` #### 1.2.4 文件夹创建完成，目录如下 ```bash . ├─ docs │ ├─ .vitepress ├─ theme # 自定义主题目录 ├─ index.ts └─ style.css │ │ └─ config.mts # 文档首页的概览、导航栏、侧边栏、链接、文字等等主题配置 │ ├─ api-examples.md # 默认的API示例使用文档 │ ├─ markdown-examples.md # 默认的markdown示例文档 │ └─ index.md # 文档的首页 └─ package.json ``` ![image-20240322192558491.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/db19bca2fc794a5e9e75ca49ebb21f83~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1024&h=768&s=101215&e=png&b=262833) api-examples.md和markdown-examples.md这两个示例文档可以删掉，并在config.mts的sidebar删掉相关链接。下面开始项目目录的配置准备： ## 首页配置参考文档：[默认主题—主页](https://vitepress.dev/zh/reference/default-theme-home-page#home-page) `docs`目录下的`index.md`便是博客文档的首页 ![image-20240322220220466.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/287aaeb8a4774fe28bae1aa48094ec8b~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1920&h=911&s=62384&e=png&b=ffffff) index.md文档如下： ```bash --- # 文档：https://vitepress.dev/zh/reference/default-theme-home-page#home-page layout: home title: 鹤屿编程学习笔记 titleTemplate: 记录自己的编程学习笔记 hero: name: 鹤屿编程学习笔记 # text: 记录自己的编程学习笔记 tagline: "正在开发中" # 首页右边Logo设置 # image: # src: /logo.png # alt: logo actions: - theme: brand text: 查看编程学习笔记 link: /order/文档指南 features: - icon: 💡 title: 文档基于vitePress构建 details: 记录自己的编程学习笔记 - icon: 📦 title: 服务端语言 details: Java、PHP、Python、Go - icon: 🤖 title: 底层编程语言 details: C/C++、Rust... --- ``` ## 站点和主题配置配置文档：[默认主题配置 | VitePress](https://vitepress.dev/zh/reference/default-theme-config) ### 1.为了方便，我们不使用ts，把config.mts改成config.js 改了config文件的后缀成.js后，以下config.js文件的内容：defineConfig()可去可不去，去掉的话如下： ```js // 去掉defineConfig()和defineConfig的导入，改成 export default {} ``` ### 2.config的站点配置文档：[站点配置 | VitePress](https://vitepress.dev/zh/reference/site-config) #### config.js配置 ```js export default { lang: "zh", // 中文，英文设置en-US title: "鹤屿编程学习笔记", // 浏览器标签标题 description: "软件开发计：开发文档和开发计划，完成功能工具，和待开发的功能和工具", base: '/program-learn-notes', // url默认前缀 appearance: true, // 暗黑模式 ignoreDeadLinks: true, // 不会因死链接而使构建失败 lastUpdated: true, // 使用 git 提交获取时间戳，使默认主题能够显示页面的上次更新时间 // markdown主题 markdown: { // 主题选择：https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes // 主题预览：https://vscodethemes.com/ // 添加自定义的主题(加载主题)：https://github.com/shikijs/shiki/blob/main/docs/themes.md#loading-theme theme: "one-dark-pro", lineNumbers: true, // 显示代码行数 }, // outDir: "../dist", // 打包输出的目录 // titleTemplate: '牧涯前端学习笔记', // 标题后缀 cleanUrls: true, // url是否带.html后缀 // 浏览器标签图标设置 head: [ [ 'link', { rel: 'icon', href: 'https://avatars.githubusercontent.com/u/48587992?v=4' } ] // ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }], ], }; ``` ### 3.主题配置主题配置文档：[默认主题配置 | VitePress](https://vitepress.dev/zh/reference/default-theme-config) #### config.js配置 ```js export default { // ***** 主题设置 ***** // 文档：https://vitepress.vuejs.org/config/theme-configs themeConfig: { logo: "/img/buding.svg", siteTitle: "鹤屿编程学习笔记", // 网站左上角标题 outlineTitle: '⚡️文档内容大纲', // 大纲标题 outline: 'deep', // 大纲显示层级：number：只显示 | [number, number]：指定层级范围显示 | 'deep'：全部显示 | false：不显示 // 使用浏览器内置索引进行模糊全文搜索 search: { provider: 'local', options: { locales: { root: { translations: { button: { buttonText: '搜索文档', buttonAriaLabel: '搜索文档' }, modal: { noResultsText: '无法找到相关结果', displayDetails: '显示详细信息', resetButtonTitle: '清除查询条件', backButtonTitle: '返回搜索结果', footer: { selectText: '选择', selectKeyAriaLabel: 'enter', navigateText: '切换', navigateUpKeyAriaLabel: 'up arrow', navigateDownKeyAriaLabel: 'down arrow', closeText: '关闭', closeKeyAriaLabel: 'escape' } } } } }, _render(src, env, md) { const html = md.render(src, env) if (env.frontmatter?.search === false) return '' // 从搜索中排除页面 if (env.relativePath.startsWith('some/path')) return '' // 转换内容——添加锚点 if (env.frontmatter?.title) return md.render(`# ${env.frontmatter.title}`) + html return html }, // 搜索配置 miniSearch: { /** * @type {Pick} */ options: { /* ... */ }, /** * @type {import('minisearch').SearchOptions} * @default * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } } */ searchOptions: { /* ... */ } }, } }, // 使用 algolia 搜索框 // search: { // provider: 'algolia', // options: { // appId: '1L6FRXPKEM', // apiKey: '934b4c2e67a08d72d379c9af236c5859', // indexName: 'program-learn-notes', // placeholder: '请输入关键词', // buttonText: '搜索', // searchParameters: { // faeFilters: ['tags:guide,api'] // } // }, // }, // 右上角导航 nav: [ { text: "🌍我的个人网站", link: "" }, ], // 右上角导航中显示带有图标的社交帐户链接 socialLinks: [ // { icon: 'discord', link: 'https://github.com/' }, // { icon: 'facebook', link: 'https://github.com/' }, // { icon: 'instagram', link: 'https://github.com/' }, // { icon: 'linkedin', link: 'https://github.com/' }, // { icon: 'slack', link: 'https://github.com/' }, // { icon: 'twitter', link: 'https://github.com/' }, // { icon: 'youtube', link: 'https://github.com/' }, // { icon: 'github', link: 'https://github.com/muyaCode/program-learn-notes' }, { icon: { svg: `` }, link: 'https://gitee.com/muyaCode/program-learn-notes' }, // { // icon: { // svg: `` // }, // link: 'https://muyacode.github.io/program-learn-notes' // } ], // *****左边侧栏导航***** sidebar: { "/": [ { text: "🌟文档指南", collapsible: true, // 可折叠 collapsed: true, // 初始不折叠 items: [ { text: "文档指南", link: "/order/文档指南" }, { text: "markdown图标", link: "/order/markdown图标" }, ], }, { text: "🌟Java", collapsible: true, // 可折叠 collapsed: true, // 初始不折叠 items: [ { text: "", link: "/Document/Java/", }, ] }, { text: "🌟Go", collapsible: true, // 可折叠 collapsed: true, // 初始不折叠 items: [ { text: "", link: "/Document/Go/", }, ] }, { text: "🌟Python", collapsible: true, // 可折叠 collapsed: true, // 初始不折叠 items: [ { text: "", link: "/Document/Python/", }, ] }, { text: "🌟PHP", collapsible: true, // 可折叠 collapsed: true, // 初始不折叠 items: [ { text: "", link: "/Document/PHP/", }, ] }, { text: "🌟C/C++", collapsible: true, // 可折叠 collapsed: true, // 初始不折叠 items: [ { text: "", link: "/Document/C-C++/", }, ] }, { text: "🌟Rust", collapsible: true, // 可折叠 collapsed: true, // 初始不折叠 items: [ { text: "", link: "/Document/Rust/", }, ] }, ] }, // 编辑 editLink: { pattern: 'https://gitee.com/muyaCode/program-learn-notes/edit/main/docs/:path', text: '在 Gitee上编辑此页' }, // 自定义上次更新的文本和日期格式 lastUpdated: { text: '上次更新：', formatOptions: { dateStyle: 'full', timeStyle: 'medium' } }, docFooter: { prev: '上一篇', next: '下一篇' }, // 右边文档大纲下面的-卡片广告 // carbonAds: { // code: '卡片广告 code', // placement: '卡片广告布置' // }, // 首页页脚配置。您可以添加消息和版权。仅当页面由于设计原因不包含边栏时，才会显示页脚。 footer: { message: 'Released under the MIT License.', copyright: 'Copyright © 2024 heyu' }, }, } ``` #### 为了方便维护，我们把主题的主要模块抽取出来 1.`docs/.vitepress`目录中新建`config` 文件夹，然后把以下模块： - `search`（浏览器搜索配置） - `algolia` （配置外部搜索） - `nav`（顶部右上角自定义导航） - `socialLinks`（顶部右上角导航中显示带有图标的社交帐户链接） - `sidebar`（🌟文章的侧边导航：写的markdown文档要配置文章的标题和路径链接🌟）等抽取成模块： ![image-20240322211243802.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/4095a7547618471fadbf1c610dfd3fd4~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=272&h=285&s=11649&e=png&b=242530) 然后config.js导入，使用如下： ```js import search from "./config/search"; // import algolia from "./config/algolia"; import socialLinks from "./config/socialLinks"; import nav from "./config/nav"; import sidebar from "./config/sidebar"; // 配置文档：https://vitepress.vuejs.org/config/introduction export default { // ***** 主题设置 ***** // 文档：https://vitepress.vuejs.org/config/theme-configs themeConfig: { logo: "/img/buding.svg", siteTitle: "鹤屿编程学习笔记", // 网站左上角标题 outlineTitle: '⚡️文档内容大纲', // 大纲标题 outline: 'deep', // 大纲显示层级：number：只显示 | [number, number]：指定层级范围显示 | 'deep'：全部显示 | false：不显示 // 使用浏览器内置索引进行模糊全文搜索 search, // 使用 algolia 搜索框 // search: { // provider: 'algolia', // options: algolia, // }, // 右上角导航 nav, // 右上角导航中显示带有图标的社交帐户链接 socialLinks, // *****左边侧栏导航***** sidebar, // 编辑 editLink: { pattern: 'https://gitee.com/muyaCode/program-learn-notes/edit/main/docs/:path', text: '在 Gitee上编辑此页' }, // 自定义上次更新的文本和日期格式 lastUpdated: { text: '上次更新：', formatOptions: { dateStyle: 'full', timeStyle: 'medium' } }, docFooter: { prev: '上一篇', next: '下一篇' }, // 右边文档大纲下面的-卡片广告 // carbonAds: { // code: '卡片广告 code', // placement: '卡片广告布置' // }, // 首页页脚配置。您可以添加消息和版权。仅当页面由于设计原因不包含边栏时，才会显示页脚。 footer: { message: 'Released under the MIT License.', copyright: 'Copyright © 2024 heyu' }, }, }; ``` ## 自定义主题按照我们前面创建docs文件夹的时候的主题选项，docs/.vitepress目录中会生成theme目录和文件。详情参考文档定义：[自定义主题 | VitePress](https://vitepress.dev/zh/guide/custom-theme) ## 写MarkDwom文档在原有的大众化的MarkDwom文档格式基础上，有了些改变，可以显示更多样式，参考文档：[Markdown 扩展 | VitePress](https://vitepress.dev/zh/guide/markdown) ## 写MarkDwom文档的坑 ### html标签不要直接写像这样： ![image-20240322222648402.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a6ccea061e3b49d0b6ab1e7ad93fd4e2~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1024&h=627&s=113733&e=png&b=272934) 运行报错： ```bash build error: SyntaxError: Element is missing end tag. ``` 这个报错时没有显示哪个具体的文档报错的，如果你的文档一多，就比较比较难找。所以养成习惯，代码块外的html的标签需要添加上``，编程引用代码块的形式，如：`

`，这样，打包就不会报错了。 ![image-20240322222859232.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e3115c4c90a845f3acc6e64947da082c~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=84&h=33&s=722&e=png&b=2c2e3b) ## 编译打包终端运行 ```bash pnpm run docs:build ``` ## 上传Gitee和GitHub部署博客参考文档： ### 1.上传git仓库，然后配置部署博客 #### 1.1.1 Gitee仓库部署的前置限制比较多完成以下才能使用部署gitpage - 需要身份证实名Gitee（审核需要大概一周吧）。 - 仓库必须开源 - 上传的仓库总体积不能超过1024MB(1GB) - 仓库种的单张图片不能大于5MB，否则不能部署文档。 - 每一次上传之后，都需要重新部署gitpage Gitee仓库可以同步到GitHub #### 1.1.2 Gitee仓库部署 ##### 推送分支和创建 `gh-pages`分支 1.Gitee创建一个仓库，先把marster主分支上传到远程仓库，然后远程再创建一个`gh-pages`分支，此分支用于打包的项目目录的上传。 2.打包后的项目目录：`docs/.vitepress/dist` ，终端中进入该目录 ```bash cd docs/.vitepress/dist ``` 3.然后，把该目录下的文件，推送到远程分支`gh-pages`，推送后的分支目录文件如下： ![image-20240322234412402.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7a0ba862667e4886b82f05a0de315c88~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=904&h=429&s=44223&e=png&b=fefdfd) ##### 部署Gitee Pages服务仓库中点击：服务——Gitee Pages ![image-20240322234826795.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/55fca03b19c240fa97da8326fd8584a7~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=910&h=521&s=95387&e=png&b=fdfdfd) 选择分支，然后部署 ![image-20240322235122912.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9e68bbdf3f1a47acbb44baf87ad6cdc0~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1222&h=769&s=87212&e=png&b=fef9f9) 我这里部署过，显示的是【更新】，没有部署过显示的是【启动】部署成功后，会有提示部署好的网址，打开就能看到部署好的文档网站了。 **gitee仓库每次提交gh-pages分支，都需要手动再在这里点击更新部署，而github仓库是自动更新。** #### 3.gitee关联github仓库，并同步 1.在仓库中点击管理 2.点击仓库镜像管理 3.点击添加镜像 ![image-20240322235516725.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f81ae213c94941df9e3e92952571dd61~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1211&h=587&s=86940&e=png&b=fdfaf9) 看文档如何获取私人令牌，然后选择仓库——添加 ![image-20240322235735517.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d298e883bc604c888c0186e30b7757f0~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1243&h=564&s=67477&e=png&b=fefdfd) 添加完成后是这样子的 ![image-20240322235818799.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a4140c98ad7d44618c0405e66554bf43~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1235&h=540&s=63426&e=png&b=fdfaf9) 这样，每当上传到gitee仓库时，也会同步到github仓库。 github的pages部署如下： #### 1.2.1 GitHub GitHub部署静态文档网站，没有上面Gitee的这些限制，但是国内访问比较慢。 #### 1.2.2 GitHub仓库部署 1.重复上面Gitee仓库的创建和提交上传分支的操作，创建和提交上传marster和gh-pages这两个分支。 2.点击仓库顶部第二栏：`Settings`——Pages——然后选择分支——save部署 ![image-20240323001148955.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/351a630e53e542b6b1079dd914b8da3f~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1429&h=872&s=123738&e=png&b=ffffff) **github仓库每次提交gh-pages分支，是自动更新部署的。** 不像gitee仓库，需要手动更新 ### 2.写了个脚本，能自动化打包和上传到github或gitee仓库 #### 项目根目录中新建：deploy.sh ```sh #!/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 打包生成静态文件 pnpm run docs:build # 进入生成的文件夹 cd docs/.vitepress/dist # 如果是发布到自定义域名 # echo 'www.example.com' > CNAME time=$(date "+%Y-%m-%d %H:%M:%S") git init git add -A git commit -m "GitHub Action 自动部署：$time" # # 如果发布到 https://.github.io -f 强制推送 # git push -f git@github.com:/.github.io.git master git push -f git@gitee.com:muyaCode/program-learn-notes.git master:gh-pages # 发布到Gitee # git push -f git@github.com:muyaCode/program-learn-notes.git master:gh-pages # 发布到GitHub # 退出到本项目根目录 cd - # 删除打包成的dist文件目录 rm -rf docs/.vitepress/dist # echo "仓库地址：https://github.com/muyaCode/program-learn-notes" # echo "文档地址：https://muyacode.github.io/program-learn-notes/" # 格式化输出带颜色配置：https://www.shuzhiduo.com/A/D854N3mVzE/ echo -e "Gitee仓库地址：\033[44;37m https://gitee.com/muyaCode/program-learn-notes/ \033[0m" echo -e "GiteePages文档地址：\033[47;30m https://muyacode.gitee.io/program-learn-notes/ \033[0m" # echo -e "GitHub仓库地址：\033[44;37m https://github.com/muyaCode/program-learn-notes/ \033[0m" # echo -e "GitHubPages文档地址：\033[47;30m https://muyacode.github.io/program-learn-notes/ \033[0m" ``` #### package.json添加执行该脚本的命令： ```json "scripts": { "deploy": "bash deploy.sh" }, ``` #### 这样脚本命令就可以点击运行了 ![image-20240322214508285.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/687c35b960764551b96741d42ae37457~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1024&h=768&s=126047&e=png&b=272934) 运行脚本成功提交代码后 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/69d70098330741a48171378f2dc13aab~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1610&h=271&s=41532&e=png&b=282a36) 运行之后等待脚本运行完成，然后再去github或gitee仓库看看是否成功，gitee仓库的话，需要手动更新部署，github仓库自动更新。 ### 3.文档过大打包编译时错误 vitepress默认的打包设置内存比较小，如果你的文档很多，项目体积很大，打包则会报错： ![image-20240322224914053.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ee4146d8653c460aad60d50a5022b2e4~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1184&h=732&s=78591&e=png&b=282a36) vitepress 内存溢出(JS stacktrace)，是因为内存设置不足，这时候我们可以以下添加内存设置：在 `node_modules/.bin/vitepress` 文件和 `node_modules/.bin/vitepress.CMD` 文件修改增加运行内存： **vitepress** 文件：`--max_old_space_size=49152` ![image-20240322225203863.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/caaefaccc4cc4305bb5648e83761a9b9~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=867&h=432&s=44849&e=png&b=272935) ```sh if [ -x "$basedir/node" ]; then exec "$basedir/node" " --max_old_space_size=49152 $basedir/../vitepress/bin/vitepress.js" "$@" else exec node --max_old_space_size=49152 "$basedir/../vitepress/bin/vitepress.js" "$@" fi ``` **vitepress.CMD** 文件：`--max_old_space_size=49152` ![image-20240322225240828.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6e19c9764abe46fc82a39ba7d2d557a2~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=764&h=334&s=34912&e=png&b=272935) ```sh @IF EXIST "%~dp0\node.exe" ( "%~dp0\node.exe --max_old_space_size=49152" "%~dp0..\vitepress\bin\vitepress.js" %* ) ELSE ( @SET PATHEXT=%PATHEXT:;.JS;=;% node --max_old_space_size=49152 "%~dp0..\vitepress\bin\vitepress.js" %* ) ``` 这样打包就不会出错了。 ## 以上项目的参考仓库 gitee：可以直接克隆下来编写在Document中创建目录和markdow文件、编写markdown文档，再在`docs.vitepress\config\sidebar.js`中添加markdown文章文档目录和链接。最后再根据上面的部署教程，运行 `deploy.sh` 脚本部署自己的博客文档等静态网站。