VitePress学习笔记

VitePress学习
- 搭建和运行
- 编写内容
- - md
  - vue
- 配置
- - 站点配置
  - 配置search
  - - [search 提示词替换](#search 提示词替换)
  - 使用第三方主题
  - 自定义主题
  - 设置文档根目录
- 国际化
- - 文档
  - nav
  - sidebar
  - search
  - 其他
- 插件
- - vitepress插件
  - markdown-it插件
项目开发

VitePress学习

搭建和运行

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

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

sh 复制代码

npm add -D vitepress

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

bash 复制代码

npx vitepress init

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

运行

sh 复制代码

npm run docs:dev

如果你是全局安装的vitepress，可能直接执行这个命令是不行的。

因为项目目录无依赖。

需要执行

sh 复制代码

npm i -D vitepress

或者你使用全局的vitepress

bash 复制代码

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

html 复制代码

<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

## Markdown Content

The count is: {{ count }}

<button :class="$style.button" @click="count++">Increment</button>

<style module>
.button {
  color: red;
  font-weight: bold;
}
</style>

使用组件

html 复制代码

<script setup>
import CustomComponent from '../../components/CustomComponent.vue'
</script>

# Docs

This 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文件

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

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

ts 复制代码

import { LocaleConfig } from 'vitepress';

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

export default JapaneseConfig;

现在就是这样了.

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

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

ts 复制代码

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。

搜索栏配置国际化，先配置一个默认的。

ts 复制代码

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

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

在config.mts中配置

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

ts 复制代码

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

文档

安装

bash 复制代码

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

在config.mts中引入

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

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

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

ts 复制代码

  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,
                },
              ],
            },
          };