1 什么是MkDocs MkDocs---markdown项目文档工具,是一个用来创建项目文档的快速、简单、完美的静态站点生成器,文档源码使用Markdown来撰写,用一个yml文件作为配置文档。它具有如下几个优点: 1.1 任意托管 构建完全的静态 HTML 站点 , 可以将它托管到 GitHub pages, Amazon S3 等任意地方。 1.2 大量主题 默认包含大量美观的主题。可以从 bootstrap, readthedocs 和 12 款 bootswatch 主题中选择。 1.3 即时预览 内建的开发服务器使你在撰写文档的时候就即时预览. 它甚至能在保存更改时自动载入, 只需刷新浏览器就可以查看更改。 1.4 易于配置 可以配置文档主题。 1.5 交叉索引 使用MkDocs链接语法创建交叉索引。 2 什么是Materialfor MkDocs 一个MkDocs的MaterialDesign主题。(A Material Design theme for MkDocs )Material 是MkDocs的主题,是针对项目文档的优秀静态网点生成器。它是基于Google的Material Design 指南搭建的。 3 安装 因为mkdocs是基于python对markdown的文档生成器,安装mkdocs之前得先安装python。 3.1Mkdocs安装
3.2Material for MkDocs安装
3.3环境配置 要在cmd上运行mkdocs还需要配置系统环境,控制面板-集团和安全-系统-高级系统设置-系统变量,找到path,添加mkdocs.exe的路径。其路径根据安装方法不同位置不同,pip安装的是在python安装目录下的scripts下。最后以管理员身份打开cmd,输入mkdocs没报错就是安装成功了。 4 用mkdocs创建静态网页 4.1项目创建 管理员模式打开cmd,输入
生成一个my-project项目文件夹,里面有docs文件夹和mkdocs.yml配置文件,会给你一个预览网址默认是http://127.0.0.1:8000/,用默认浏览器打开它就可以看见网页。 4.2网页内容配置 因为mkdocs的即时预览,你修改的配置会直接载入网页。 用管理员模式下的cmd打开mkdocs.yml进行修改
在次级目录下还可以创建目录。
网页内容就是放在docs文件下的.md文件。 配置完后在my-project文件夹下用cmd输入
完成后会生成一个site文件夹,这个文件夹里的内容就是生成的静态网站。 5 结语 生成的静态网站可以部署到readthedoc和github上。团队可以用这个来管理博客和文档。因为不支持中文搜索,管理博客还是有一些问题的,主要还是用来管理文档的。 实习主编 | 王楠岚 责 编 | 王自强 where2go 团队 |
|