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