MkDocs的使用-流程图、序列图

标准Markdown语法并不支持流程图、序列图的绘制，好在MkDocs能够通过第三方插件pymdown-extensions扩展来实现。

在前篇中已经完成了pymdown-extensions的安装，现在可以使用superfences来实现流程图及序列图的绘制。

superfences使用flowchart.js和sequence-diagram.js两种javascript库来实现流程图和序列图的绘制，配置过程如下：

一 、修改mkdocs.yml配置

site_name: My Docs
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/raphael/2.2.7/raphael.min.js - https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js - https://cdnjs.cloudflare.com/ajax/libs/js-sequence-diagrams/1.0.6/sequence-diagram-min.js - https://cdnjs.cloudflare.com/ajax/libs/flowchart/1.6.5/flowchart.min.js - js/umlconvert.js
markdown_extensions:
- pymdownx.superfences

superfences首先将md文件中```flow以及```sequence区块部分的逻辑代码转换为

<pre class="uml-flowchart"><code>...</code></pre>

及

<pre class="uml-sequence-diagram"><code>...</code></pre>

并插入到最终生成的html文件中，然后umlconvert.js通过flowchart.js、sequence-diagram.js将html页面标签中的uml-flowchart和uml-sequence-diagram部分的逻辑代码转换为流程图以及序列图。

二 、添加umlconvert.js

在docs目录下创建js目录，进入js目录创建umlconvert.js，文件内容如下：

(function (document) {
function convertUML(className, converter, settings) {
var charts = document.querySelectorAll("pre." + className + ',div.' + className),
arr = [],
i, j, maxItem, diagaram, text, curNode,
isPre;

// Is there a settings object?
if (settings === void 0) {
settings = {};
}

// Make sure we are dealing with an array
for(i = 0, maxItem = charts.length; i < maxItem; i++) arr.push(charts[i]);

// Find the UML source element and get the text
for (i = 0, maxItem = arr.length; i < maxItem; i++) {
isPre = arr[i].tagName.toLowerCase() == 'pre';
if (isPre) {
// Handles <pre><code>
childEl = arr[i].firstChild;
parentEl = childEl.parentNode;
text = "";
for (j = 0; j < childEl.childNodes.length; j++) {
curNode = childEl.childNodes[j];
whitespace = /^\s*$/;
if (curNode.nodeName === "#text" && !(whitespace.test(curNode.nodeValue))) {
text = curNode.nodeValue;
break;
}
}
// Do UML conversion and replace source
el = document.createElement('div');
el.className = className;
parentEl.parentNode.insertBefore(el, parentEl);
parentEl.parentNode.removeChild(parentEl);
} else {
// Handles <div>
el = arr[i];
text = el.textContent || el.innerText;
if (el.innerText){
el.innerText = '';
} else {
el.textContent = '';
}
}
diagram = converter.parse(text);
diagram.drawSVG(el, settings);
}
};

function onReady(fn) {
if (document.addEventListener) {
document.addEventListener('DOMContentLoaded', fn);
} else {
document.attachEvent('onreadystatechange', function() {
if (document.readyState === 'interactive')
fn();
});
}
}

onReady(function(){
convertUML('uml-flowchart', flowchart);
convertUML('uml-sequence-diagram', Diagram, {theme: 'simple'});
});
})(document);

二 、添加test.md

```flow
st=>start: Start:>http://www.google.com[blank]
e=>end:>http://www.google.com
op1=>operation: My Operation
sub1=>subroutine: My Subroutine
cond=>condition: Yes
or No?:>http://www.google.com
io=>inputoutput: catch something...
st->op1->cond
cond(yes)->io->e
cond(no)->sub1(right)->op1
```

```sequence
Title: Here is a title
A->B: Normal line
B-->C: Dashed line
C->>D: Open arrow
D-->>A: Dashed open arrow
```

三 、运行MkDocs

可惜没有得到想要的结果，发现MkDocs（版本0.16.3）生成的html页面里使用了require.js，和flowchart.js冲突，将次问题反馈到了pymdown-extensions的开源站点，得到的解决办法是更改MkDocs使用的主题

四 、修改MkDocs主题

安装了若干主题，终于找到一个不冲突的mkdocs-material

1.安装

pip install mkdocs-material

2.修改mkdocs.yml

site_name: My Docs
theme: 'material'
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/raphael/2.2.7/raphael.min.js - https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js - https://cdnjs.cloudflare.com/ajax/libs/js-sequence-diagrams/1.0.6/sequence-diagram-min.js - https://cdnjs.cloudflare.com/ajax/libs/flowchart/1.6.5/flowchart.min.js - js/umlconvert.js
markdown_extensions:
- pymdownx.superfences