我是一个程序员，文档是个很头疼的东东。一直在找一个对于自己来说好用一些的生成文档的工具，前一阵找到了Markdown，相当不错的写作工具，最近一直在使用。最近公司要求生成内部API文档，写起来很麻烦，特别是生成word文档，需要的各种格式调整，费时费力。我使用Markdown写了一个版本，但是其他人都用word写的，无法整合，于是我在网上不停的寻找，终于让我找到了，Justmd + Markdown + Python + Mkdocs , 这个组合，简直是无与伦比啊。
简单的说明一下：
1. 软件安装
- 首先需要安装Python， 我安装的3.6版本，网上有很多安装教程，这里就不一一说明了。
- 安装Justmd，市面上有不少的 Markdown 编辑器，每个编辑器都有各自的特色功能。 justmd编辑器，除了能在多平台上使用以外，它还有一个智能粘贴的功能。
这个智能粘贴功能支持图片、HTML 内容、Word 文档内容等，简单来说，就是将你复制的富文本内容转换为 Markdown 语言并粘贴，省去了你不少的操作呢。使用方法也很简单，复制后，使用菜单或者快捷键「Alt + V」来粘贴就可以了。 - Markdown工具，可以使用上面的Justmd，也可以使用其他的工具， 我个人觉得Typora更适合我个人的写作。这部分仁者见仁智者见智，我就不多做推荐了
- 安装Mkdocs，这个是Python下的一个模块，使用PIP安装即可，如下：
pip install mkdocs
2. 生成
安装完上述工具后就可以使用Markdown工具进行写作了，根据需要可以写多个Markdown文档，统一写完后，放在同一个目录下面。
然后在命令行中生成Mkdocs目录
mkdocs new project-name
cd project-name
image.png
使用任意文本工具修改mkdocs.yml文档，格式说明如下：
site_name: MkLorum (文档的名称)
pages: (所有界面都在这个下面)
- Home: index.md (目录名称：文档名称.md)
- About: about.md
theme: readthedocs (主题设置)
default.theme
readthedocs.theme
上面是2个主题的效果图。
3. 启动项目：
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes
然后在浏览器中访问http://127.0.0.1:8000 就可以看到相应的文档了。
基本介绍就到这里了，如果有任何问题，可以给我留言大家一起学习。
后记：
Mkdocs还可以生成静态页面，命令如下：
$mkdocs build --clean
生成 的静态页面在同目录下：site文件夹
网友评论