VitePress学习笔记
- VitePress学习
- 搭建和运行
- 编写内容
- md
- vue
- 配置
- 站点配置
- 配置search
- search 提示词替换
- 使用第三方主题
- 自定义主题
- 设置文档根目录
- 国际化
- 文档
- nav
- sidebar
- search
- 其他
- 插件
- vitepress插件
- markdown-it插件
- 项目开发
- 原始需求和方案
- 自动化流程
- 权限限制
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,},],},};
)
 - 加法器)
