Vitepress的文檔渲染基礎教程

更新時間：2022年10月27日 15:57:27 作者：小鑫同學

這篇文章主要為大家介紹了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 文檔渲染基礎的資料請關注腳本之家其它相關文章！

您可能感興趣的文章: