快捷導(dǎo)航

Vitepress的文檔渲染基礎(chǔ)教程

更新時(shí)間：2022年10月27日 15:57:27 作者：小鑫同學(xué)

這篇文章主要為大家介紹了Vitepress的文檔渲染基礎(chǔ)教程，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步，早日升職加薪

1.引言

Vitepress的文檔渲染目的就是將程序員日常所寫的Markdown文件編譯為Html文件，并添加了更多的插件來豐富MD文件的功能，就比如說Vuejs組件在MD文件中渲染等等，為了我們可以在使用Vitepress的時(shí)候可以更隨心所欲的定制一些功能，我們要先搞一搞明白Vitepress是如何將MD文檔渲染成HTML的~

看完可以明白這3點(diǎn)？

MD文檔轉(zhuǎn)HTML文檔流程；
如何支持代碼塊高亮；
如何實(shí)現(xiàn)自定義容器；

2. 實(shí)現(xiàn)MD文檔轉(zhuǎn)HTML文檔

2.1 請按如下項(xiàng)目結(jié)構(gòu)準(zhǔn)備我們的實(shí)驗(yàn)環(huán)境~

├─markdown-it-demo
│  ├─src
│  │  ├─index.ts
│  │  ├─temp.md
│  ├─index.html
└─ └─package.json

2.2 利用markdown-it模塊實(shí)現(xiàn)文檔轉(zhuǎn)換：

markdown-it 是目前比較通用的MD語法解析模塊，快速且易于擴(kuò)展，遵循COmmonMark規(guī)范，且有大量的社區(qū)插件~

執(zhí)行安裝模塊命令：pnpm i markdown-it @types/markdown-it -D；
導(dǎo)入markdown-it模塊并實(shí)例化md對象；

import markdownIt from "markdown-it";
// 實(shí)例化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進(jìn)行轉(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)自動(dòng)在瀏覽器打開index.html文檔；

3. 實(shí)現(xiàn)MD支持代碼塊高亮

代碼塊高亮所使用的模塊時(shí)highlight.js，該模塊同時(shí)內(nèi)置了很多常見的代碼塊樣式文件可供選擇~

3.1 第一步改造markdownIt對象的構(gòu)造函數(shù)：

highlight屬性配置的函數(shù)傳入code片段和代碼方言兩部分，通過在hljs庫中查找對應(yīng)的方言來利用hljs庫實(shí)現(xiàn)代碼的快速高亮，當(dāng)無法查找到對應(yīng)的方言時(shí)將返回僅僅轉(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結(jié)構(gòu)的轉(zhuǎn)換，但是完成高亮還需要樣式配合渲染，我們這里可以通過在輸出output內(nèi)容到index.html時(shí)將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. 實(shí)現(xiàn)MD支持自定義容器

自定義容器是MD文檔默認(rèn)并不支持的一種語法，在Vuejs的文檔有很多的應(yīng)用，實(shí)現(xiàn)自定義容易需要用到markdown-it-container模塊~

markdownIt通過插件的形式利用markdown-it-container來實(shí)現(xiàn)自定義容器，通過配置validate來做渲染前的語法校驗(yàn)，通過render函數(shù)來組中容器部分的HTML結(jié)構(gòu)~

::: 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結(jié)構(gòu)的轉(zhuǎn)換，在自定義容器的時(shí)候我們預(yù)留的css名稱，我們還是需要在輸出index.html文件的時(shí)候自定義樣式文檔~

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. 總結(jié)

通過使用markdown-it、highlight.js、markdown-it-container模塊實(shí)現(xiàn)了Markdown到HTML的文檔轉(zhuǎn)換，代碼塊高亮和自定義容器，VItepress搭建的組件庫文檔中的組件渲染和源碼展示功能就需要用到自定義容器的解析和組裝自定義的Vue組件實(shí)現(xiàn)高級(jí)功能~

本文項(xiàng)目已推送至GitHub，歡迎克隆演示：git clone

https://github.com/OSpoon/awesome-examples.git

以上就是Vitepress的文檔渲染基礎(chǔ)教程的詳細(xì)內(nèi)容，更多關(guān)于Vitepress 文檔渲染基礎(chǔ)的資料請關(guān)注腳本之家其它相關(guān)文章！

您可能感興趣的文章: