VitePress学习笔记

VitePress学习

搭建和运行

搭建和运行很简单，多看文档。

如果你是在自己的项目中增加vitepress在项目中安装即可，需要全局安装的话加 -g

npm add -D vitepress

初始化项目，在想要初始化的目录中执行

npx vitepress init

根据喜好配置，目录以及标题等等。

运行

npm run docs:dev

如果你是全局安装的vitepress，可能直接执行这个命令是不行的。
因为项目目录无依赖。

需要执行

npm i -D vitepress

或者你使用全局的vitepress

npx vitepress dev ./vitepress

不过还是建议安装到项目这样依赖明细更清楚。
我这里用的是v1.6.3当然你可以使用最新的

运行起来后

这里是home页面，对应文件为index.md

这种写法是fontmatter

你也可以不用这种写法，用常规md写。

编写内容

md

支持基础的md以及拓展，见文档https://vitepress.dev/zh/guide/markdown

可以自己尝试。

vue

由于vitepress是基于vue的，他是可以使用vue来嵌入到md的。
见文档https://vitepress.dev/zh/guide/using-vue

<script setup>
import { ref } from 'vue'const count = ref(0)
</script>## Markdown ContentThe count is: {{ count }}<button :class="$style.button" @click="count++">Increment</button><style module>
.button {color: red;font-weight: bold;
}
</style>

使用组件

<script setup>
import CustomComponent from '../../components/CustomComponent.vue'
</script># DocsThis is a .md using a custom component<CustomComponent />

基本上vue的写法都支持。

配置

站点配置

https://vitepress.dev/zh/reference/site-config
文件位置.vitepress/config.mts

可以自己尝试，对照文档。其实也不用记，用的时候查阅一下就行。

配置search

开启这个配置。我们使用本地检索local。
内嵌的是minisearch，你可以查看minisearch文档来额外的配置，或者看ts定义

文档位置https://vitepress.dev/zh/reference/default-theme-search#mini-search-options

search 提示词替换

见文档https://vitepress.dev/zh/reference/default-theme-search#local-search-i18n
可以先不配置i18n来直接修改文本内容，比如

使用第三方主题

比如vitepress-theme-teek 在npmjs上搜vitepress-theme可以搜到很多，这里举个例子,具体配置还是要看第三方主题的文档的。

npm i vitepress-theme-teek

在.vitepress目录下心中theme/index.ts文件

import Teek from 'vitepress-theme-teek';
import 'vitepress-theme-teek/index.css';export default {extends: Teek,
};

在config.mts中，把原先的配置传递给第三方主题的defineTeekConfig

自定义主题

vitepress学习-自定义主题

大概就是利用useData获取运行时的数据，然后可以重写一套我们自己的布局和组件。渲染还是用vitepress 内置的markdown-it。

取数据和某些渲染场景的话，看这个
https://vitepress.dev/zh/reference/runtime-api#content

设置文档根目录

比如想把文档丢丢在docs目录中

国际化

国际化需要写多套文档，每个语言的都写一遍，不过应该可以通过第三方插件来快速完成。

文档

试一下正常的配置。
首先我们准备三个文件
一个是默认语言的，其他两个是其他语言的。

默认是中文。

这里切换后，发现路径会变化的，其实就是文档路径对吧。


除了内容的国际化，还有其他的国际化，如nav,sidebar还有搜索框。

nav

这里把配置拆分下，不同语言丢到不同的配置文件里面。

import { LocaleConfig } from 'vitepress';const JapaneseConfig: LocaleConfig = {jp: {label: '日本語',lang: 'jp',themeConfig: {nav: [{ text: 'ホーム', link: '/' },{ text: '例', link: '/markdown-examples' },],},},
};export default JapaneseConfig;

现在就是这样了.

其实就是再写一遍日语的配置。此时没有单独配置themeConfig的用的还是公用的配置。

sidebar

在日语配置文件里面增加一个sidebar配置

const JapaneseConfig: LocaleConfig = {jp: {label: '日本語',lang: 'jp',themeConfig: {nav: [{ text: 'ホーム', link: '/' },{ text: '例', link: '/jp/markdown-examples' },],sidebar: [{text: '例',items: [{ text: 'マークダウン例', link: '/jp/markdown-examples' },{ text: 'ランタイム API 例', link: '/jp/api-examples' },],},],},},
};

现在是不能点击侧边栏的，只是现实成日文了，jp文件夹下没有这两个文件的。只是改了侧边栏的语言显示。

search

search本地搜索用的是minisearch。
搜索栏配置国际化，先配置一个默认的。

 search: {provider: 'local',options: {translations: {button: {buttonText: '搜索文档',buttonAriaLabel: '搜索文档',},modal: {noResultsText: '无法找到相关结果',resetButtonTitle: '清除查询条件',footer: {selectText: '选择',navigateText: '切换',},},},locales: {},},},

然后配置locales，如何知道这个的呢。看ts定义。

在config.mts中配置

这里我把JapaneseSearch配置专门拉出来写了。

export const JapaneseSearch: Record<string,Partial<Omit<DefaultTheme.LocalSearchOptions, 'locales'>>
> = {jp: {translations: {button: {buttonText: 'ドキュメントの検索',buttonAriaLabel: 'ドキュメントの検索',},modal: {noResultsText: '関連する結果を見つけることができませんでした',resetButtonTitle: 'クエリー条件の消去',footer: {selectText: 'せんたく',navigateText: '切り替え',closeText: '閉じる',},},},},
};

效果如下

其他

能在locals下配置的有这些。


比如配置title

效果

除了这些以外，也要看某个配置里面是否有国际化配置选项。

插件

vitepress插件

使用一个插件。
vitepress-plugin-llms

文档
安装

npm install vitepress-plugin-llms --save-dev

在config.mts中引入

在.vitepress/theme/index.ts中引入，没有theme/index.ts则创建

import DefaultTheme from 'vitepress/theme'
import type { Theme } from 'vitepress'
import CopyOrDownloadAsMarkdownButtons from 'vitepress-plugin-llms/vitepress-components/CopyOrDownloadAsMarkdownButtons.vue'export default {extends: DefaultTheme,enhanceApp({ app }) {app.component('CopyOrDownloadAsMarkdownButtons', CopyOrDownloadAsMarkdownButtons)}
} satisfies Theme

然后引入markdown-it插件

看看效果

复制出来的md

---
url: /desc.md
---
# 介绍我是一个人类

这里本地运行点击这两个可能会报错，我是丢掉服务器点击的，部署没问题。

在哪里搜插件呢npmsjs

https://www.npmjs.com/search?q=vitepress-plugin

比如这个插件能拓展不少东西。

vitepress-plugin-mermaid

markdown-it插件

除了能使用vitepress插件(里面可能包含有markdown-it插件)外，
还可以使用markdown-it插件，因为vitepress内置的markdown渲染用的是这个。

搜markdown-it插件也可以去npmjs搜
https://www.npmjs.com/search?q=markdown-it-plugin

有些已经内置了，找自己需要的就行。
或者你也可以自己写，之前需要视频显示的时候也写了个简单的，不过针对特定格式写法。
https://dmhsq.blog.csdn.net/article/details/148876825?spm=1011.2415.3001.5331

项目开发

原始需求和方案

原始需求是期望一个第三方富文本编辑器来编写应用使用文档，自动转化为静态站点。然后根据链接中的id来动态展示侧边栏。

通过一次开发需求总结。需求在之前的飞书文档转md基础上，增加了CICD，这个CICD不是运维去发布的，是交给了使用人员。在此基础上增加了权限，包括侧边栏的动态化，地址栏强行跳转则转到404。具体流程如下。

自动化流程

使用人员点击页面上的刷新，通过后端调用jenkins的远程触发link进行构建，构建完成后推送data.json。

之前的记录一次飞书文档转md嵌入vitepress做静态站点

其实也是有不少问题的，不过过了一个周期又迭代了一次。

因为不需要home所以home页纯显示loading了，这个页面简洁，给人一种加载中的错觉。

之前的文章写的loading构建后也是有点问题的，所以采用了这种方式，进来后在home页面，实际上就在loading。
当数据加载完成后，跳转其他页面就行。

路由拦截的话，可以用watch监听route。

在这个里面写一些逻辑，当然还可以在setup中，来看下theme.ts的定义。

我是在enhanceApp里面写的获取数据，在setup里面写路由处理逻辑，使用pinia来通知数据的变化，

权限限制

从上面的获取数据流程拿到路由数据。

限制跳转就是监听路由判断是否有权限，没有权限跳转404。
正常情况下使用不用考虑这个，一般租户id固定，页面固定，在页面内操作无这个问题，主要是处理地址栏直接访问无权限路由。

除此之外也要限制搜索，比如无权限的页面，不能让他搜索到。
因为vitepress配置的local是用的minisearch。所以配置下minisearch。

在enhanceApp中获取完成数据后动态设置siteData

  siteData.value = {...siteData.value,themeConfig: {...siteData.value.themeConfig,search: {...siteData.value.themeConfig.search,options: {...siteData.value.themeConfig.search.options,miniSearch: {...siteData.value.themeConfig.search.options.miniSearch,searchOptions: {// 过滤筛选结果 去掉无页面权限的filter: (doc) => {try {const path = doc.id.split('#')[0];if (listData.find((item) => item.link == path)) {return true;}return false;} catch (error) {return true;}},},},},},// 覆盖侧边栏sidebar: [{text: '文档',items: sideBar,},],},};