简介
mkdocs 是一个简单、快速 并且 完全静态的网站生成工具。用以构建项目文档页面。
使用Markdown编写文档源文件，YAML 编写配置文件
可以部署到任何地方
由于 mkdocs 生成的是完全静态页面，所以它可以部署到任何地方（Github pages,Amazon S3,Gitlab pages,或任何你能想到的地方
基础配置
首先，需要一个配置文件
mkdocs.yml:
site_name: 文档或项目名
pages:
- 1 主页: index.md
theme: material #readthedocs
这里，描述了标题，并且有一个pages ，下面是各个页面的导航结构。
可配置多层结构如:
pages:
- A:
-A.1: a.1.md
-A.2: a.1.md
docs/index.md:
## 这里是示例主页
进阶配置
这里，使用一个带比较完备扩展的示例
mkdocs.yml:
site_name: 文档或项目名
pages:
- 1 主页: index.md
theme: material #readthedocs
extra:
palette:
primary: 'cyan'
accent: 'purple'
markdown_extensions:
- toc
- smarty
- pymdownx.arithmatex
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.critic
- pymdownx.details
- pymdownx.emoji:
emoji_generator: !!python/name:pymdownx.emoji.to_svg
- pymdownx.inlinehilite
- pymdownx.magiclink
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tilde
plugins:
- search
docs/index.md:
## 这里是示例主页
扩展语法参考: pydownx
使用docker进行构建
docker run --rm -v `pwd`:/docs squidfunk/mkdocs-material:2.2.0 build -d public
使用原生python 进行安装
pip install mkdocs mkdocs-material pymdown-extensions
mkdocs 使用甘特图
该功能由于比较复杂所以放在 mkdocs-diagram 进行迭代开发
在mkdocs.yaml 文件添加
site_name: 文档或项目名
pages:
- 1 主页: index.md
theme: material #readthedocs
extra:
palette:
primary: 'cyan'
accent: 'purple'
extra_javascript:
- https://unpkg.com/mermaid@7.1.0/dist/mermaid.min.js
- 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:
- toc
- smarty
- pymdownx.arithmatex
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.critic
- pymdownx.details
- pymdownx.emoji:
emoji_generator: !!python/name:pymdownx.emoji.to_svg
- pymdownx.inlinehilite
- pymdownx.magiclink
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.superfences:
custom_fences: [
{name: flow, class: uml-flowchart}
,{name: sequence, class: uml-sequence-diagram}
,{name: mermaid, class: uml-mermaid}
]
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tilde
plugins:
- search
添加文件
docs/js/umlconvert.js
//from: http://www.cmky.net/blog/tool/mkdocs.html
//author: humboldt
//new on : https://github.com/humboldt-xie/mkdocs-diagram
function EachTag(arr,tag,callback){
var i=0,maxItem=arr.length;
for (; i < maxItem; i++) {
if(arr[i].tagName && arr[i].tagName.toLowerCase() == tag.toLowerCase()){
callback(arr[i])
}
}
}
function code2Text(codeEl){
var text = "",j;
for (j = 0; j < codeEl.childNodes.length; j++) {
var curNode = codeEl.childNodes[j];
whitespace = /^\s*$/;
if (curNode.nodeName === "#text" && !(whitespace.test(curNode.nodeValue))) {
text = curNode.nodeValue;
break;
}
}
return text
}
function mermaidConvert(index,text,el){
var insertSvg = function(svgCode) {
el.innerHTML = svgCode;
};
mermaid.parse(text)
mermaid.render('mermaid-' + index.toString(), text, insertSvg);
return null
}
function flowchartConvert(index,text,el){
diagram=flowchart.parse(text)
diagram.drawSVG(el,{});
return null
}
function sequenceConvert(index,text,el){
diagram=Diagram.parse(text)
diagram.drawSVG(el,{theme: 'simple'});
return null
}
var diagramType={
"gantt":mermaidConvert,
"sequenceDiagram":mermaidConvert,
"flowchart":mermaidConvert,
"graph TD":mermaidConvert,
"graph LR":mermaidConvert,
"uml-flowchart":flowchartConvert,
"uml-sequence-diagram":sequenceConvert
}
function convertUML() {
var pre= document.querySelectorAll("pre")
for (var i=0; i<pre.length; i++){
var codeEl= pre[i];
var parentEl = pre[i];
EachTag(parentEl.childNodes,"code",function(code){
codeEl=code;
})
var text=code2Text(codeEl);
var type=mermaid.mermaidAPI.detectType(text);
var conv=diagramType[type];
if(text.indexOf("graph")==0){
conv=mermaidConvert;
}
var pclass=parentEl.classList
for(var j=0;!conv && j<parentEl.classList.length;j++){
conv=diagramType[parentEl.classList[j]]
if(conv){
break;
}
}
if(conv){
el = document.createElement('div');
el.className = type;
try {
parentEl.parentNode.insertBefore(el, parentEl);
conv(i,text,el)
parentEl.parentNode.removeChild(parentEl);
}catch(err){
codeEl.title=err.str;
}
}
}
};
function onReady(fn) {
if (document.addEventListener) {
document.addEventListener('DOMContentLoaded', fn);
} else {
document.attachEvent('onreadystatechange', function() {
if (document.readyState === 'interactive')
fn();
});
}
}
(function (document) {
onReady(function(){
convertUML();
});
})(document);
一些示例 效果
```mermaid
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
section A section
Completed task:done, des1, 2014-01-06,2014-01-08
Active task:active, des2, 2014-01-09, 3d
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
section A section
Completed task:done, des1, 2014-01-06,2014-01-08
Active task:active, des2, 2014-01-09, 3d
```mermaid
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
Future task2 : des4, after des3, 5d
section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser and jison :crit, done, after des1, 2d
Create tests for parser :crit, active, 3d
Future task in critical line :crit, 5d
Create tests for renderer :2d
Add to mermaid :1d
section Documentation
Describe gantt syntax :active, a1, after des1, 3d
Add gantt diagram to demo page :after a1 , 20h
Add another diagram to demo page :doc1, after a1 , 48h
section Last section
Describe gantt syntax :after doc1, 3d
Add gantt diagram to demo page :20h
Add another diagram to demo page :48h
```
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
Future task2 : des4, after des3, 5d
section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser and jison :crit, done, after des1, 2d
Create tests for parser :crit, active, 3d
Future task in critical line :crit, 5d
Create tests for renderer :2d
Add to mermaid :1d
section Documentation
Describe gantt syntax :active, a1, after des1, 3d
Add gantt diagram to demo page :after a1 , 20h
Add another diagram to demo page :doc1, after a1 , 48h
section Last section
Describe gantt syntax :after doc1, 3d
Add gantt diagram to demo page :20h
Add another diagram to demo page :48h
输入：
```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
```
输出：
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
```
输出：
Title: Here is a title
A->B: Normal line
B-->C: Dashed line
C->>D: Open arrow
D-->>A: Dashed open arrow
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
section A section
Completed task:done, des1, 2014-01-06,2014-01-08
Active task:active, des2, 2014-01-09, 3d
使用mermaid原理
通过遍历dom各个pre标签，取到里面code 内容，然后转换成text。
并识别text 开头，是gantt 等mermaid 格式，然后使用mermaid 进行绘制。
如果转换失败，则设置pre 或code 的title 显示错误信息。这样既不干扰阅读，又能看到错误信息。
同时，还使用了 - pymdownx.superfences:
superfences 会将制定的语言，打上相应的class，这样可以在前端找到它。
如 {name: flow, class: uml-flowchart} 则会在 ```flow 生成的pre 标签打上 class=uml-flowchart
