文档章节

MkDocs 文档生成逻辑浅析

极光推送
 极光推送
发布于 2017/02/09 15:05
字数 588
阅读 28
收藏 0

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.

Markdown 文档解析

YAML 配置文件

载入 YAML 的配置,将配置文件的内容读取为 Python 内容。

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

Python 字典

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

Python 字典

Jinja2 内容生成

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

Jinja2 内容生成

Jinja2 模板文件

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

MkDocs 比较巧妙的实现了内容和表现的分离,虽然没有数据库,但是使用了结构化的 markdown 文件,解析为 Python 内容,然后通过 Jinja2 模板,最后生成 HTML。

MkDocs http://www.mkdocs.org/

作者:不知道自己是谁(极光)

http://www.jianshu.com/p/c9410da484fb

© 著作权归作者所有

共有 人打赏支持
极光推送
粉丝 42
博文 175
码字总数 184243
作品 1
深圳
个人站长
私信 提问
mkdocs与jekyll 创建静态网站

mkdocs教程:http://www.mkdocs.org/#installation(英文) http://markdown-docs-zh.readthedocs.org/zhCN/latest/(中文) MacDown的下载包:http://yunpan.cn/cdmKrfvZs2fsc (提取码:6a8e)......

黑黑的豆
2015/08/06
0
0
如何编写 Python 文档生成器

在我刚开始接触Python的日子里,我最喜欢做的事情之一是坐在解释器旁使用内置help功能来检查类和方法,决定下一个要敲的内容。这个功能导入一个对象,遍布它的成员,取出文档注释,生成一个类...

oschina
2016/11/28
2.9K
0
(mkdocs)一款使用markdown编写website的插件

推荐一款markdown的文档website 自带服务(开源) 可以添加镶嵌html代码 *分目录结构 0.准备 默认已经安装python $ python --versionPython 2.7.2$ pip --versionpip 1.5.2 1.安装mkdocs $ pi...

mingle
2016/01/06
94
0
静态网站生成器--MkDocs

MkDocs 可以同时编译多个markdown文件,形成书籍一样的文件。有多种主题供你选择,很适合项目使用。 MkDocs 是快速,简单和华丽的静态网站生成器,可以构建项目文档。文档源文件在 Markdown...

不避风云
2015/11/06
1K
1
iOS 移动端面向文档开发

之前的解耦架构生成器在实际项目中已经顺利测试通过了, 现在要做的是将文档规范出来, 并扩展到Android, HTML5端的共用, 实现面向文档开发. 参考链接: iOS 执行.py脚本生成解耦架构 iOS 执行....

Castie1
2017/11/25
0
0

没有更多内容

加载失败,请刷新页面

加载更多

oh-my-zsh 自定义

GitHub 地址 基于 oh-my-zsh 的自定义配置,增加了一些个人常用插件与皮肤。 采用的是 git submodule 来维护,包括 oh-my-zsh,之所以这么搞,主要是手头有多台 linux 需要维护, 每台机器、...

郁也风
今天
6
0
Docker安装踩坑:E_FAIL 0x80004005的解决

参考 菜鸟教程--Windows Docker 安装 http://www.runoob.com/docker/windows-docker-install.html 官方文档-Install Docker Toolbox on Windows https://docs.docker.com/toolbox/toolbox_in......

karma123
今天
5
0
js垃圾回收机制和引起内存泄漏的操作

JS的垃圾回收机制了解吗? Js具有自动垃圾回收机制。垃圾收集器会按照固定的时间间隔周期性的执行。 JS中最常见的垃圾回收方式是标记清除。 工作原理:是当变量进入环境时,将这个变量标记为“...

Jack088
昨天
17
0
大数据教程(10.1)倒排索引建立

前面博主介绍了sql中join功能的大数据实现,本节将继续为小伙伴们分享倒排索引的建立。 一、需求 在很多项目中,我们需要对我们的文档建立索引(如:论坛帖子);我们需要记录某个词在各个文...

em_aaron
昨天
27
0
"errcode": 41001, "errmsg": "access_token missing hint: [w.ILza05728877!]"

Postman获取微信小程序码的时候报错, errcode: 41001, errmsg: access_token missing hint 查看小程序开发api指南,原来access_token是直接当作parameter的(写在url之后),scene参数一定要...

两广总督bogang
昨天
33
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部