Vitepress的文檔渲染基礎教程
1.引言
Vitepress的文檔渲染目的就是將程序員日常所寫的Markdown文件編譯為Html文件，并添加了更多的插件來豐富MD文件的功能，就比如說Vuejs組件在MD文件中渲染等等，為了我們可以在使用Vitepress的時候可以更隨心所欲的定制一些功能，我們要先搞一搞明白Vitepress是如何將MD文檔渲染成HTML的~
看完可以明白這3點？
- MD文檔轉(zhuǎn)HTML文檔流程；
- 如何支持代碼塊高亮；
- 如何實現(xiàn)自定義容器；
2. 實現(xiàn)MD文檔轉(zhuǎn)HTML文檔
2.1 請按如下項目結構準備我們的實驗環(huán)境~
├─markdown-it-demo │ ├─src │ │ ├─index.ts │ │ ├─temp.md │ ├─index.html └─ └─package.json
2.2 利用markdown-it模塊實現(xiàn)文檔轉(zhuǎn)換：
markdown-it 是目前比較通用的MD語法解析模塊，快速且易于擴展，遵循COmmonMark規(guī)范，且有大量的社區(qū)插件~
- 執(zhí)行安裝模塊命令：
pnpm i markdown-it @types/markdown-it -D； - 導入
markdown-it模塊并實例化md對象；
import markdownIt from "markdown-it"; // 實例化md-it對象 const md = new markdownIt();
- 通過
fs-extra模塊讀取放置在src下的temp.md文件，讀取后的Buffer數(shù)組通過toString()轉(zhuǎn)為字符串；
const rawMd = fs.readFileSync(path.resolve(__dirname, "temp.md")).toString();
- 利用md對象的
render函數(shù)來講rawMd進行轉(zhuǎn)換；
const output = md.render(rawMd);
- 轉(zhuǎn)換完成后將
output內(nèi)容輸出到index.html文件中；
fs.writeFileSync(path.resolve(__dirname, "../index.html"), `
${output}
`);
- 在轉(zhuǎn)換完成后可以利用
child_process.exec(root-path)自動在瀏覽器打開index.html文檔；
3. 實現(xiàn)MD支持代碼塊高亮
代碼塊高亮所使用的模塊時highlight.js，該模塊同時內(nèi)置了很多常見的代碼塊樣式文件可供選擇~
3.1 第一步改造markdownIt對象的構造函數(shù)：
highlight屬性配置的函數(shù)傳入code片段和代碼方言兩部分，通過在hljs庫中查找對應的方言來利用hljs庫實現(xiàn)代碼的快速高亮，當無法查找到對應的方言時將返回僅僅轉(zhuǎn)義后的html片段~
const md = new markdownIt({
highlight: (str: string, lang: string) => {
const defaultCode: string = `<pre class="hljs"><code>${md.utils.escapeHtml(str)}</code></pre>`;
if (lang && hljs.getLanguage(lang)) {
try {
return `<pre class="hljs"><code>${hljs.highlight(str, { language: lang, ignoreIllegals: true }).value}</code></pre>`
} catch (__) {
return defaultCode;
}
}
return defaultCode;
}
});
3.2 第二部整合output內(nèi)容和高亮樣式文本：
第一步的操作僅僅完成了由code片段到html結構的轉(zhuǎn)換，但是完成高亮還需要樣式配合渲染，我們這里可以通過在輸出output內(nèi)容到index.html時將hljs中喜歡的樣式文檔路徑傳入到html文件來加載~
const output = md.render(rawMd);
const styles = `
<link rel="stylesheet" href="./node_modules/highlight.js/styles/a11y-dark.css" rel="external nofollow" rel="external nofollow" >
`;
// 輸出html文本
fs.writeFileSync(path.resolve(__dirname, "../index.html"), `
${styles}
${output}
`);
更多的樣式文檔可以在./node_modules/highlight.js/styles選擇~
4. 實現(xiàn)MD支持自定義容器
自定義容器是MD文檔默認并不支持的一種語法，在Vuejs的文檔有很多的應用，實現(xiàn)自定義容易需要用到markdown-it-container模塊~
markdownIt通過插件的形式利用markdown-it-container來實現(xiàn)自定義容器，通過配置validate來做渲染前的語法校驗，通過render函數(shù)來組中容器部分的HTML結構~
::: warning *here be dragons* ::: ↓↓↓↓↓↓↓↓↓↓轉(zhuǎn)換為↓↓↓↓↓↓↓↓↓↓ <div class="warning"> <em>here be dragons</em> </div>
md.use(require("markdown-it-container"), "warning", {
validate: (params: string) => {
return params.trim().match(/^warning+(.*)$/m);
},
render: (tokens: Array<Token>, idx: number) => {
const m = tokens[idx].info.trim().match(/^warning+(.*)$/m);
if (tokens[idx].nesting === 1) {
return `<div class="warning">${md.utils.escapeHtml(m ? m[1] : '')}`
} else {
return '</div>\n';
}
}
})
提示：通過tokens[idx]取到的數(shù)據(jù)如下圖所示~
- 上面的處理依舊是MD到HTML結構的轉(zhuǎn)換，在自定義容器的時候我們預留的css名稱，我們還是需要在輸出
index.html文件的時候自定義樣式文檔~
const output = md.render(rawMd);
const styles = `
<link rel="stylesheet" href="./node_modules/highlight.js/styles/a11y-dark.css" rel="external nofollow" rel="external nofollow" >
<style>
.warning{
margin: 28px 0;
padding: 10px 14px 4px 22px;
border-radius: 8px;
overflow-x: auto;
transition: color .5s,background-color .5s;
position: relative;
font-size: 14px;
line-height: 1.6;
font-weight: 500;
color: #0000008c;
background-color: #f9f9f9;
border: 1px solid #ffc517;
}
.hljs {
padding: 5px 8px;
border-radius: 5px;
}
</style>
`;
// 輸出html文本
fs.writeFileSync(path.resolve(__dirname, "../index.html"), `
${styles}
${output}
`);
5. 總結
通過使用markdown-it、highlight.js、markdown-it-container模塊實現(xiàn)了Markdown到HTML的文檔轉(zhuǎn)換，代碼塊高亮和自定義容器，VItepress搭建的組件庫文檔中的組件渲染和源碼展示功能就需要用到自定義容器的解析和組裝自定義的Vue組件實現(xiàn)高級功能~
本文項目已推送至GitHub，歡迎克隆演示：git clone
https://github.com/OSpoon/awesome-examples.git
以上就是Vitepress的文檔渲染基礎教程的詳細內(nèi)容，更多關于Vitepress 文檔渲染基礎的資料請關注腳本之家其它相關文章！
相關文章
教你使用vue-autofit 一行代碼搞定自適應可視化大屏
這篇文章主要為大家介紹了使用vue-autofit 一行代碼搞定自適應可視化大屏教程詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪2023-05-05
這篇文章主要介紹了vue3.0 CLI - 3.2 - 路由的初級使用教程,非常不錯，具有一定的參考借鑒價值，需要的朋友可以參考下2018-09-09
這篇文章主要介紹了Vue仿微信app頁面跳轉(zhuǎn)動畫效果，非常不錯，具有一定的參考借鑒價值,需要的朋友可以參考下2019-08-08
這篇文章主要介紹了vue中props值的傳遞，在vue中父組件要正向的向子組件傳遞數(shù)據(jù)或者參數(shù)，子組件接收到后根據(jù)參數(shù)的不同來進行對應的渲染，這個正向的數(shù)據(jù)傳遞在vue組件中就是通過props來實現(xiàn)的，需要的朋友可以參考下2009-05-05
文件上傳是我們在開發(fā)Web應用時經(jīng)常遇到的功能之一,為了提升用戶體驗,我們可以利用HTML5的拖放API來實現(xiàn)拖拽文件上傳的功能,本文將介紹如何在Vue3中實現(xiàn)這一功能,文中有詳細的代碼示例供大家參考,需要的朋友可以參考下2023-12-12
這篇文章主要為大家介紹了Vue3從0搭建Monorepo項目組件庫示例詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪2023-02-02
這篇文章主要為大家詳細介紹了vue實現(xiàn)原生下拉刷新，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下2022-03-03
vue-hooks是簡化組件定義、復用狀態(tài)邏輯的一種最新嘗試,下面這篇文章主要給大家介紹了關于vue2中@hook的解析與妙用的相關資料,文中通過實例代碼介紹的非常詳細,需要的朋友可以參考下2023-03-03
Vue異步更新DOM及$nextTick執(zhí)行機制解讀
這篇文章主要介紹了Vue異步更新DOM及$nextTick執(zhí)行機制解讀，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2023-03-03
vue-cli2.x項目優(yōu)化之引入本地靜態(tài)庫文件的方法
這篇文章主要介紹了vue-cli2.x項目優(yōu)化之引入本地靜態(tài)庫文件的方法，小編覺得挺不錯的，現(xiàn)在分享給大家，也給大家做個參考。一起跟隨小編過來看看吧2018-06-06