深入淺出 VuePress（一）：如何做到在 Markdown 中使用 Vue 語法

前言

在 vuepress 剛出時，我就覺得這是個很值得追更的開源專案。果不其然，裡面眾多的前端程式設計技巧讓我受益良多。

於是在週末這種日子裡，人家追劇我追碼。

今天，我就和大家分享下 vuepress 是如何做到在 Markdown 中使用 Vue 語法的。

原理

眾所周知，Markdown 是一種標記語言，類似於 HTML，它也有對應的語法和詞法。而 Vue 說白了也是一種語法，關鍵在於，Markdown 和 Vue 程式碼都可以被解釋成 HTML。

聰明的讀者應該想到了：新增一箇中間過程，讓 Vue 轉成 Markdown 或者讓 Markdown 轉成 Vue，是不是就可以實現在 Markdown 中使用 Vue 語法了呢？

讓我們再考慮一下兩個方案的實現難點：

1. Vue -> Markdown：template 和 style 部分還好，可 js 部分怎麼辦？
2. Markdown -> Vue：可以將 markdown 程式碼解釋成 html 或者 js 混入到 vue 程式碼中。

很顯然，第二種方案實現起來更靠譜些，所以尤雨溪也是這樣選的：

vuepress 在 Markdown 中使用 Vue 語法原理

在語法之間的轉換工作上，webpack 的 loader 可是很擅長的。所以，vuepress 自定義了一個 markdownLoader 來將 Markdown 轉成 Vue，再通過 vue-loader 得到最終的 HTML。

程式碼實現

markdownLoader

這是一個自定義的 loader，可參考如何編寫一個 loader？

1. 這個 loader 接收一個引數，裡面包含一個 markdown-it 例項，作者用它來把 markdown 解釋成 html。
2. 得到 html 後將之包裹在 template 標籤內，返回。

`<template>\n` +
    `<div class="markdown">${html}</div>\n` +
`</template>\n`

主要過程其實就這兩步。當然，vuepress 還在 markdownLoader 裡做了很多其他的事情，比如解析 yaml front matter、推斷標題、獲取 markdown 裡提升的 style、script 等標籤。

自己實現一個 demo

接下來，大家可以跟我一起實現一個基本的 demo。完整程式碼可見 github。

1. 新建一個 Vue 專案
   我們使用 vue-cli(v2.9.6) 新建一個專案：

   
   
   

   vue-cli 新建專案

2. 編寫 markdownLoader

• 2.1 引入 markdown-it

  npm install markdown-it --save
  

• 2.2 新建 markdownLoader 檔案

  const markdown = require('markdown-it')
  
  module.exports = function(src) {
    const html = markdown().render(src)
    return (
      `<template>\n` +
        `<div class="markdown">${html}</div>\n` +
      `</template>\n`
    )
  }
  

• 2.3 在 webpack 的 module rules 配置中新增 markdownLoader

  {
    test: /\.md$/,
    use: [
      { loader: 'vue-loader' },
      {
        loader: require.resolve('./markdownLoader')
      }
    ]
  }
  

3. 在 Vue 檔案裡使用 markdown 檔案

• 3.1 在 src/components 新建一個 markdown.md

## 我是一個 markdown 
{{1+2}}

• 3.2 在 src/router/index 中引入 markdown

 const Markdown = () => import('@/components/markdown.md')

• 3.3 將這個元件新增進路由裡去

{
  path: '/md',
  name: 'Markdown',
  component: Markdown
}

結果

在 Markdown 中使用 React(JSX) 語法

既然可以在 markdown 裡寫 vue，那在 markdonw 裡面寫 react 理論上也是可以實現的：讓 markdownLoader 最後返回一個 React 元件，之後使用 babel-loader 轉成 js。

這一次我們是將 markdown 轉 jsx 再包裹在一個 React 元件(函式或者類)裡：

return (
    `import React from 'react';
    ${registerComponent}
    function R() {
        return (
        <div>
            <div className="markdown">${html}</div>
        </div>)
    }
    export default R;\n`
)

有興趣的讀者可以自行實現完整的 react 版本的 markdownLoader 程式碼。

結語

本文實現的 demo 只對 markdownLoader 的關鍵步驟做了實現，實際上還有很多問題需要解決，如瀏覽器的 API 訪問限制、程式碼塊和高亮的處理等需要解決，這篇文章就不涉及了。

此係列文章還會給大家介紹 webpack 擴充、markdown-it 擴充、單元測試、外掛系統等。如果您喜歡這篇文章的話，別記得點個贊噢~