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

转载于:https://my.oschina.net/u/3465063/blog/892515