MkDocs 文档生成逻辑浅析
Markdown 和 MkDocs 简介
Markdown 的语法简洁明了、学习容易,而且功能比纯文本更强,因此有很多人用它写博客。世界上最流行的博客平台 WordPress 和大型 CMS 如 Joomla 、Drupal 都能很好的支持 Markdown 。
MkDocs 是一个用于创建项目文档的快速,简单的静态站点生成器。文档源码使用 Markdown 来撰写,用一个 YAML 文件作为配置文档。
MkDocs 处理的是一系列的 Markdown 文档,然后将 Markdown 文档的内容解析出来,保存在 Python 字典中,最后 Jinja2 模板把内容生成为 html 。
MkDocs 如何将 Markdown 内容解析出来?又是如何将文档内容结构化的?
Markdown 文档解析
使用 Python-Markdown 解析文件,然后返回 html_content ,table_of_contents ,meta 。对内容做了初步的处理,从 markdown 文件,转换为 Python 相关变量。
Python-Markdown 简介
This is a Python implementation of John Gruber’s Markdown. It is almost completely compliant with the reference implementation, though there are a few very minor differences. See John’s Syntax Documentation for the syntax rules.

YAML 配置文件
载入 YAML 的配置,将配置文件的内容读取为 Python 内容。
YAML是一种直观的能够被电脑识别的的数据序列化格式,容易被人类阅读,并且容易和脚本语言交互。YAML类似于XML,但是语法比XML简单得多,对于转化成数组或可以hash的数据时是很简单有效的。

Python 字典
获取页面内容,从 markdown 中解析的内容,存入 Python 字典中,为后续 Jinja2 的调用做准备。

Jinja2 内容生成
载入 Jinja2 模板,结合之前抽取的内容生成 HTML 文件。
Jinja2 是一个现代的,设计者友好的,仿照 Django 模板的 Python 模板语言。 它速度快,被广泛使用,并且提供了可选的沙箱模板执行环境保证安全。

Jinja2 模板文件
toc.html 的代码
模板文件中有之前的 Python 变量,比如 nav.item ,会被替换为对应的内容。

MkDocs 比较巧妙的实现了内容和表现的分离,虽然没有数据库,但是使用了结构化的 markdown 文件,解析为 Python 内容,然后通过 Jinja2 模板,最后生成 HTML。
MkDocs http://www.mkdocs.org/
作者:不知道自己是谁(极光)http://www.jianshu.com/p/c9410da484fb
MkDocs 文档生成逻辑浅析的更多相关文章
- 【C#附源码】数据库文档生成工具支持(Excel+Html)
[2015] 很多时候,我们在生成数据库文档时,使用某些工具,可效果总不理想,不是内容不详细,就是表现效果一般般.很多还是word.html的.看着真是别扭.本人习惯用Excel,所以闲暇时,就简单的 ...
- 微软开源全新的文档生成工具DocFX
微软放弃Sandcastle有些年头了,微软最近开源了全新的文档生成工具DocFX,目前支持C#和VB,类似JSDoc或Sphinx,可以从源代码中提取注释生成文档之外,而且还有语法支持你加入其他的文 ...
- DBImport v3.44 中文版发布:数据库数据互导及文档生成工具(IT人员必备)
前言: 距离上一个版本V3.3版本的文章发布,已经是1年10个月前的事了. 其实版本一直在更新,但也没什么大的功能更新,总体比较稳定,所以也不怎么写文介绍了. 至于工作上的事,之前有半年时间跑去学英语 ...
- .NET平台开源项目速览(4).NET文档生成工具ADB及使用
很久以前就使用ADB这个工具来生成项目的帮助文档.功能强大,在学习一些开源项目的过程中,官方没有提供CHM帮助文档,所以为了快速的了解项目结构和注释.就生成文档来自己看,非常好用.这也是一个学习方法吧 ...
- (转)Doxygen文档生成工具
http://blog.csdn.net/lostaway/article/details/6446786 Doxygen 是一个支持 C/C++,以及其它多种语言的跨平台文档生成工具.如同 Java ...
- Sandcastle----强大的C#文档生成工具
最近客户索要产品的二次开发类库文档,由于开发过程中并没有考虑过此类文档,而且项目规范比较,持续时间比较长,经手人比较多,还真是麻烦,如果人工制作文档需要是一个比较大的工程.还好有这个文档生成工具,能够 ...
- JAVA基础学习之命令行方式、配置环境变量、进制的基本转换、排序法、JAVA文档生成等(1)
1.命令行方式 dos命令行,常见的命令: dir:列出当前目录下的文件以及文件夹 md:创建目录 rd:删除目录 cd:进入指定目录 cd..:退回到上一级目录 cd/:退回到根目录 del:删除文 ...
- 使用Objective-C的文档生成工具:appledoc
使用Objective-C的文档生成工具:appledoc 前言 做项目的人多了,就需要文档了.今天开始尝试写一些项目文档.但是就源代码来说,文档最好和源码在一起,这样更新起来更加方便和顺手.象 Ja ...
- 使用Objective-C的文档生成工具
前言 做项目的人多了,就需要文档了.今天开始尝试写一些项目文档.但是就源代码来说,文档最好和源码在一起,这样更新起来更加方便和顺手.象Java语言本身就自带javadoc命令,可以从源码中抽取文档.今 ...
随机推荐
- jquery offset positon 获取位置不准的解决方法
问题: 本地开发时,由于使用了图片,而且使用了offset().top涉及到图片所在的div距离计算的部分,本地开发一切都没问题:但是部署到服务器上时却出现布局错乱,经过排查发现总是少了一个图片高度的 ...
- 297. Serialize and Deserialize Binary Tree二叉树的序列化和反序列化(就用Q)
[抄题]: Serialization is the process of converting a data structure or object into a sequence of bits ...
- impdp报错ORA-39083 ORA-02304 Object type TYPE failed to create
环境Red Hat Enterprise Linux Server release 5.8 (Tikanga)ORACLE Release 11.2.0.3.0 Production 我用expdp, ...
- c++ std::unordered_set
std::unordered_set template < class Key, // unordered_set::key_type/value_type class Hash = hash& ...
- [C++] Sign and magnitude,Ones' complement and Two's complement
Sign and magnitude,Ones' complement and Two's complement
- Lucene.Net(转)
出处:http://www.cnblogs.com/piziyimao/archive/2013/01/31/2887072.html 做过站内搜索的朋友应该对Lucene.Net不陌生,没做过的也许 ...
- 38 写一个函数,求一个字符串的长度,在main函数中输入字符串,并输出其长度。
题目:写一个函数,求一个字符串的长度,在main函数中输入字符串,并输出其长度. public class _038PrintLength { public static void main(Stri ...
- Word文档发布到CSDN博客
目前大部分的博客作者在写博客这件事情上都会遇到以下3个痛点:1.所有博客平台关闭了文档发布接口,用户无法使用Word,Windows Live Writer等工具来发布博客.2.发布到博客或公众号平台 ...
- asp.net WebAPI 问题 iisnode默认不支持PUT和DELETE的解决
因为iisnode的自动重启服务器方便,一直用的它来作为开发中的node服务器,今天一个delete命令过去,得到一个405(?好像是)错误,让我很郁闷. 用原生的node试一下,是完美支持的,本来打 ...
- Oracle 表关联性 Update 语句的改写,推荐改写方法1
同事写了一个逻辑稍复杂的Update 语句,觉得在代码可读性上有些转圈,交给我帮忙改下. 以下根据原SQL,使用两种方法进行改写,个人推荐方法1的改写.方法2拆分两个SQL来写,代码可读性最强,但是S ...