讓 Markdown 中的程式碼可以實時執行

背景

讓 Markdown 中的程式碼可以實時執行，為什麼會有這樣一個需求？

在我們前端團隊中，技術相關的文件都採用 Markdown 編寫， 文件中往往會伴隨很多示例程式碼，我們希望大家在閱讀文件的時候，可以執行示例程式碼，看到效果。

需求

• 讓 Markdown 中的程式碼可以執行，並預覽效果。
• 程式碼可以線上編輯。
• 不影響整個文件流的佈局。
• 支援 React, 支援程式碼高亮。
• 可以配置 babel。

明確需求以後，寫了一個 React 元件來滿足這些功能， react-code-view ， 首先看一下效果：

線上預覽: simonguo.github.io/react-code-…

原理

• 就通過 markdown-loader 與 html-loader 解析 Markdown 文件。
• 通過正規表示式取出 code ，交給 codemirror
• 把 codemirror 中的程式碼通過 babel 編譯，再通過 ReactDOM.render 渲染到指定的容器中。

安裝

npm install react-code-view
複製程式碼

配置 webpack

在 webpack 中需要新增對 markdown-loader 的支援。 需要安裝：

npm install html-loader --save-dev
npm install markdown-loader --save-dev
npm install react-markdown-reader --save-dev
複製程式碼

webpack.config.js 配置

>=webpack 2.x +

const markdownRenderer = require('react-markdown-reader').renderer;

{
  test: /\.md$/,
  use: [{
    loader: 'html-loader'
  }, {
    loader: 'markdown-loader',
    options: {
      pedantic: true,
      renderer: markdownRenderer(/**languages:Array<string>**/)
    }
  }]
}
複製程式碼

languages 預設值：["javascript", "bash", "xml", "css", "markdown", "less"];

Github: github.com/simonguo/re…

新增 Babel

示例程式碼中通常是使用到 ES2015+ , React 等，需要對程式碼實時做編譯，所以在 html 中引入 babel :

<script type="text/javascript" src="//cdn.staticfile.org/babel-standalone/6.24.0/babel.min.js"></script>
複製程式碼

示例

import CodeView from 'react-code-view';
import '~react-code-view/lib/less/index.less';

import { Button } from 'rsuite';


<CodeView dependencies={{ Button }} >
  {require('./example.md')}
</CodeView>

複製程式碼

原始碼都統一寫在 markdown 中，參考: example.md

這裡需要注意的是把需要執行的程式碼一定要放在 <!--start-code--> 與 <!--end-code--> 之間。

API

Name	Type	Default value	Description
dependencies	Object		依賴的元件
showCode	boolean	true	顯示程式碼
babelTransformOptions	Object	{ presets: ['stage-0', 'react', 'es2015'] }	babel 配置引數 options

誰在用？

• React Suite