1. 问题描述

markdown技术可以实现技术文档的快捷写作，以及输出发布。但markdown的基本功能只支持单篇文档，如何将大量的技术文档集成综合的技术手册、书籍呢？

笔者通过gitbook+看云的技术平台，实现了

mark

本文介绍这一技术的实现过程。

2. 技术背景

markdown的基础应用不再赘述，详见笔者专栏：http://www.jianshu.com/nb/6041803。

本文采用的技术框架为：

看云是一个专业的markdown技术文档、书籍的托管发布平台，也有相应的手机客户端。

关于看云平台的使用方法，详见http://help.kancloud.cn/41497。

mark

gitbook是一个国外的markdown书籍创作平台，有相应的editor编辑器。gitbook的软件及平台本身即可实现技术文档的撰写发布，但网络不畅通且不稳定，不适合国内使用。此处仅采用gitbook编辑器软件。

关于gitbook的详细应用，见http://www.jianshu.com/p/383d26cd9238。

大型技术文档的编辑发布，关键在于markd子文档的集成，以及编译方式的定义。其中的技术逻辑与LaTeX排版方式类似。

通过itbook创建的书籍项目，基本文件结构为：

mark

# Summary

* [引言](README.md)
* [理论基础](理论基础.md)
    * [导波控制方程](导波控制方程.md)
    * [导波频散曲线分析](导波频散曲线分析.md)
* [数值模拟](数值模拟.md)

{ "plugins": [
"highlight",
"tex"
]}

详见：http://help.kancloud.cn/62408。

注册看云
http://www.kancloud.cn
下载gitbook
官方下载网站为：https://www.gitbook.com/editor/，但下载速度极慢，很不稳定。
百度网盘下载更方便：链接：http://pan.baidu.com/s/1nuVG9dB 密码：8hrc
安装gitbook
安装过程按照默认配置即可，没有必要注册gitbook

看云主要作为网上的分享、发布平台，而文档项目的内容编辑主要在本地电脑，通过gitbook实现。

如此即完成了基本的项目配置工作，后续主要进行内容的创作。

其中，introduction与README.md对应，是默认的必备文件，无法删除。
First Chapter与chapter1.md对应，可以删除。

构建自己的章节框架
按照一般的布局习惯，将introduction改为引言，First Chapter删除。
按照写作需求创建章，这里实际上相当于章的标题和每章引言。

mark
输入文字内容后，gitbook会自动创建相应的markdown文件。

mark
创建具体的节内容

mark
独立目录创建
除了基本的markdown语法之外，看云支持在文档首添加[toc]，生成子文档的独立目录。效果如：

mark

每个markdown文件的内容实际上相互独立，通过SUMMARY.md组织成整理。通过gitbook创建的内容可以生成默认的SUMMARY文件：

mark

其基本语法是markdown标准语法中，无序列表和超链接的结合，但此处的超链接指向文档的子文件。：

* [引言](README.md)
* [理论基础](理论基础.md)

注意到：“理论基础”是章标题（一级），而“导波控制方程”与“导波频散曲线分析”为节标题（二级），可以手动调整逻辑层次。

mark