使用Vditor將Markdown文檔渲染成網頁(Vite+JS+Vditor)
1. 引言
編寫Markdown文檔現在可以說是程序員的必備技能了，因為Markdown很好地實現了內容與排版分離，可以讓程序員更專注于內容的創作。現在很多技術文檔，博客發布甚至AI文字輸出的內容都是以Markdown格式的形式輸出的。那么，Markdown文檔如何渲染成標準的Web網頁呢？這就要借助于一些支持Markdown格式的編輯器組件了。開源的Markdown編輯器組件有不少，Vditor是筆者認為功能比較全的一款，在這里本文就通過Vditor來實現將一個Markdown文檔渲染成網頁的具體案例。
閱讀本文可能需要的前置文章：《使用Vite創建一個動態網頁的前端項目》。
2. 實現
使用VS Code打開Vite初始化的工程，并且準備一個Markdown文檔（筆者這里用的是Vditor的說明文檔），文件組織如下所示：
my-native-js-app
├── public
│ └── demo.md
├── src
│ ├── main.js
│ └── style.css
├── index.html
└── package.json
打開終端，輸入如下指令，安裝Vditor依賴包：
npm install vditor --save
2.1 基本配置
修改index.html中的內容：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Vite App</title>
</head>
<body>
<div id="app">
<div id="md-content"></div>
</div>
<script type="module" src="/src/main.js"></script>
</body>
</html>
其中，名稱為md-content的元素就是用來顯示Markdown文檔的容器。接著是style.css：
#app {
width: 800px;
margin: 0 auto;
}
也非常簡單，就是限制了顯示Markdown文檔的寬度以及設置居中顯示。對于一個文字為主的網頁來說，文檔的寬度不宜太寬，現代主流的文檔網頁的設計都是600~800px左右。
最后就是關鍵的實現主要功能代碼main.js：
import "./style.css";
import "vditor/dist/index.css";
import Vditor from "vditor";
async function initMarkdown() {
try {
const response = await fetch("/demo.md");
if (!response.ok) {
throw new Error("網絡無響應");
}
const demoMd = await response.text();
// 顯示內容
Vditor.preview(document.getElementById("md-content"), demoMd, {
markdown: {
toc: false,
mark: true, //==高亮顯示==
footnotes: true, //腳注
autoSpace: true, //自動空格，適合中英文混合排版
},
math: {
engine: "KaTeX", //支持latex公式
inlineDigit: true, //內聯公式可以接數字
},
hljs: {
style: "github", //代碼段樣式
lineNumber: true, //是否顯示行號
},
anchor: 2, // 為標題添加錨點 0：不渲染；1：渲染于標題前；2：渲染于標題后
lang: "zh_CN", //中文
theme: {
current: "light", //light,dark,light,wechat
},
transform: (html) => {
// 使用正則表達式替換圖片路徑，并添加居中樣式及題注
return html.replace(
/<img\s+[^>]*src="\.\/([^"]+)\.([a-zA-Z0-9]+)"\s*alt="([^"]*)"[^>]*>/g,
(match, p1, p2, altText) => {
// const newSrc = `${backendUrl}/blogs/resources/images/${postId}/${p1}.${p2}`;
const newSrc = `${p1}.${p2}`;
const imgWithCaption = `
<div style="text-align: center;">
<img src="${newSrc}" class="center-image" alt="${altText}">
<p class="caption">${altText}</p>
</div>
`;
return imgWithCaption;
}
);
},
});
} catch (error) {
console.error("初始化Markdown失敗:", error);
}
}
document.addEventListener("DOMContentLoaded", initMarkdown);
實現的過程很簡單，就是在以文本的形式fetch遠端的Markdown文檔數據，然后使用Vditor.preview接口將獲取的文本數據初始化到HTML的md-content元素中。關鍵是這個接口的初始化配置參數，具體的代表的功能筆者已經注釋到代碼中。其他的配置參數非常簡單，按需進行配置即可；有點特別的是這個transform參數：
transform: (html) => {
// 使用正則表達式替換圖片路徑，并添加居中樣式及題注
return html.replace(
/<img\s+[^>]*src="\.\/([^"]+)\.([a-zA-Z0-9]+)"\s*alt="([^"]*)"[^>]*>/g,
(match, p1, p2, altText) => {
// const newSrc = `${backendUrl}/blogs/resources/images/${postId}/${p1}.${p2}`;
const newSrc = `${p1}.${p2}`;
const imgWithCaption = `
<div style="text-align: center;">
<img src="${newSrc}" class="center-image" alt="${altText}">
<p class="caption">${altText}</p>
</div>
`;
return imgWithCaption;
}
);
},
2.2 圖片居中+題注
這個配置參數是用來配置渲染成HTML頁面前的回調函數，我們可以用這個回調函數做什么呢？很簡單，可以用來實現一些特殊的元素設計。比如說，Markdown格式標準非常簡陋，只規定了如何引入圖片，但是沒有規定如何設置圖片的樣式。HTML的文檔流是從上到下、從左到右的線性布局的，默認情況下圖片是放在新的一行的最左邊的。但是實際上更最美觀的實現是圖片居中展示，并且顯示題注。
例如，在這里筆者的Markdown文檔中圖片相關的內容及最終實現效果是：
在transform指定的回調函數中，也就是這里的html其實是個HTML字符串：
<h3 id="圖片">圖片<a id="vditorAnchor-圖片" class="vditor-anchor" href="#圖片"><svg viewBox="0 0 16 16" version="1.1" width="16" height="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a></h3>
<pre><code>
</code></pre>
<p><img src="./head.jpg" alt="案例圖片" /></p>
要實現圖片居中，并且增加圖片題注就很簡單了，通過正則表達式搜索到圖片的元素<img src="./head.jpg" alt="案例圖片" />，將其替換成帶題注并且居中的div元素，也就是：
const imgWithCaption = `
<div style="text-align: center;">
<img src="${newSrc}" class="center-image" alt="${altText}">
<p class="caption">${altText}</p>
</div>
`;
最終，這個Markdown文檔的圖片的網頁渲染效果就是：
2.3 圖片源更換
筆者實現的另外一個定制功能就是實現更換圖片源地址。如果我們經常編寫Markdown文檔就知道，因為Markdown格式是文字與圖片分離的，因此對圖片資源的管理是件很麻煩的事情：如果使用base64編碼嵌到Markdown文檔里，就會影響可讀性；如果使用在線圖床，要么花錢要么花精力，要么既花錢又花精力。所以筆者還是推薦使用本地相對地址，例如：
這樣的寫法，先保證本地文檔能正常工作。但是Markdown文檔在渲染成網頁后這個相對地址就不一樣生效了，往往需要對圖片地址進行更換。更關鍵的是，像圖片這種稍微重一點的資源最好放到CDN上，所以圖片源地址的更換就是個強需求，也就是這部分代碼的意思：
return html.replace(
/<img\s+[^>]*src="\.\/([^"]+)\.([a-zA-Z0-9]+)"\s*alt="([^"]*)"[^>]*>/g,
(match, p1, p2, altText) => {
// const newSrc = `${backendUrl}/blogs/resources/images/${postId}/${p1}.${p2}`;
const newSrc = `${p1}.${p2}`;
//...
}
);
先用正則表達式找到圖片元素的內容，然后對圖片地址進行更換，更換成域內的短地址，也可以使用域外的長地址。也就是不要在Markdown文檔本身下功夫，保證本地可以正常顯示即可，更多的具體的定制功能通過Vditor渲染前回調來實現。
3. 結語
這個案例最終的顯示效果如下所示：
甚至可以表現腦圖、流程圖、時序圖、甘特圖、圖表、五線譜、流程圖等：
不得不說Vditor不一定是所有Markdown編輯器中最好用，但一定是功能比較全的編輯器了，至少比筆者使用過的tui.editor要強不少。其實通過這個功能，你就可以大致實現一個技術博客網站了。具體思路是：把這個渲染過程工具化，將Markdown格式的博客文檔批量生成靜態網頁，然后通過Web服務器進行發布；其實這也是一些靜態博客網站工具的實現思路。
浙公網安備 33010602011771號