1. 问题描述
markdown技术可以实现技术文档的快捷写作，以及输出发布。但markdown的基本功能只支持单篇文档，如何将大量的技术文档集成综合的技术手册、书籍呢？
笔者通过gitbook+看云的技术平台，实现了
- 大量技术文档的综合集成
- 发布了257页的pdf技术手册
- 实现了文档的动态更新和分享；
本文介绍这一技术的实现过程。
2. 技术背景
markdown的基础应用不再赘述，详见笔者简书专栏：http://www.jianshu.com/nb/6041803。
本文采用的技术框架为：
- 看云网站，手机客户端
- gitbook editor
下文提供下载方式。
2.1 看云
看云是一个专业的markdown技术文档、书籍的托管发布平台，也有相应的手机客户端。
关于看云平台的使用方法，详见http://help.kancloud.cn/41497。
2.2 gitbook
gitbook是一个国外的markdown书籍创作平台，有相应的editor编辑器。gitbook的软件及平台本身即可实现技术文档的撰写发布，但网络不畅通且不稳定，不适合国内使用。此处仅采用gitbook编辑器软件。
关于gitbook的详细应用，见http://www.jianshu.com/p/383d26cd9238。
3. 解决方案
大型技术文档的编辑发布，关键在于markd子文档的集成，以及编译方式的定义。其中的技术逻辑与LaTeX排版方式类似。
通过itbook创建的书籍项目，基本文件结构为：
- SUMMARY.md，为子文档集成的核心
编码内容如下，通过多级列表和超链接，定义文档的章节架构。
# Summary
* [引言](README.md)
* [理论基础](理论基础.md)
* [导波控制方程](导波控制方程.md)
* [导波频散曲线分析](导波频散曲线分析.md)
* [数值模拟](数值模拟.md)
- book.json，定义文档的定制化编译方式
以下代码中，highlight表示代码命令的高亮，tex表示对tex格式的公式编译。
{ "plugins": [
"highlight",
"tex"
]}
详见：http://help.kancloud.cn/62408。
- README.md
此为gitbook默认生成，实际上起到“前言”的作用，可以不用。
建议保留不删除，以免gitbook报错。
4. 实施示例
4.1 预备工作
- 注册看云
http://www.kancloud.cn - 下载gitbook
官方下载网站为：https://www.gitbook.com/editor/，但下载速度极慢，很不稳定。
百度网盘下载更方便：链接：http://pan.baidu.com/s/1nuVG9dB 密码：8hrc - 安装gitbook
安装过程按照默认配置即可，没有必要注册gitbook
4.2 文档项目的创建
- 进入看云的个人账户-【创建文档】
mark - 文档信息设置
此处需注意文档标识的命名规则，规范的命名如cloud-design-pattern.
mark - 记录项目git地址
如本测试项目：https://git.kancloud.cn/macheng2018/test.git
mark
看云主要作为网上的分享、发布平台，而文档项目的内容编辑主要在本地电脑，通过gitbook实现。
- 打开gitbook，
local library创建New book
mark -
进入test项目，【book】-【Sync】与网络端同步
mark -
输入看云项目的git网络地址
mark -
输入看云账户的账户密码
mark
如此即完成了基本的项目配置工作，后续主要进行内容的创作。
4.3 内容创作与编辑
-
gitbook编辑器中的初始状态如下：
章节布局：
mark
文件结构：
mark
其中，introduction与README.md对应，是默认的必备文件，无法删除。
First Chapter与chapter1.md对应，可以删除。
- 构建自己的章节框架
按照一般的布局习惯，将introduction改为引言，First Chapter删除。
按照写作需求创建章，这里实际上相当于章的标题和每章引言。
mark -
输入文字内容后，gitbook会自动创建相应的markdown文件。
mark - 创建具体的节内容
mark - 独立目录创建
除了基本的markdown语法之外，看云支持在文档首添加[toc]，生成子文档的独立目录。效果如：
mark
4.4 章节关系组织
每个markdown文件的内容实际上相互独立，通过SUMMARY.md组织成整理。通过gitbook创建的内容可以生成默认的SUMMARY文件：
其基本语法是markdown标准语法中，无序列表和超链接的结合，但此处的超链接指向文档的子文件。：
* [引言](README.md)
* [理论基础](理论基础.md)
注意到：“理论基础”是章标题（一级），而“导波控制方程”与“导波频散曲线分析”为节标题（二级），可以手动调整逻辑层次。
4.4 文档的发布
- 完成编辑后，点击【Publish&Sync】可以向看云发布
mark -
看云网站-【编辑】
mark -
看到网页版与本地编辑器效果一致-【发布文档】
mark -
确认发布
mark -
回到项目页面，【阅读】
mark - 预览页面
在预览页面可以看到很多重要信息：
文档项目的唯一网址：http://www.kancloud.cn/macheng2018/test
提供的功能有：在线阅读、下载、分享
下部可以预览概要和目录。
mark
当文档在本地有更新，重复以上的发布过程，即可实现文档的更新。
4.5 阅读与下载
-
在线阅读
在线阅读的显示效果最佳，提供导航窗格，搜索和收藏的功能。
mark -
下载
下载功能支持多种格式。但一般下载的文档格式上比在线阅读较差。
mark
PDF下载效果：
-
书签、封面、目录
mark -
正文显示效果
mark
经常在电脑端工作，且不能保证经常联网的情况下，适合下载pdf版本。
4.6 手机客户端
PDF通用性很好，但存在一定的不足：
- 排版显示效果不如在线阅读
- 不能及时更新最新的改动
与之相比，采用手机客户端阅读，体验更好。目前支持苹果ios，似乎尚无安卓版。
-
手机客户端
mark -
在网站点击【关注】后，手机端【我的收藏】即可显示相关文档
mark -
文档显示
mark -
目录
mark -
正文
mark
5. 常见问题
看云发布的pdf中，公式显示尚存问题，目前以图片链接代替。
网站提供了详细的帮助系统，详见：http://help.kancloud.cn/41497。
本文用时 2 h
