让 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