1. 問題描述

markdown技術可以實現(xiàn)技術文檔的快捷寫作，以及輸出發(fā)布。但markdown的基本功能只支持單篇文檔，如何將大量的技術文檔集成綜合的技術手冊、書籍呢？

筆者通過gitbook+看云的技術平臺，實現(xiàn)了

mark

本文介紹這一技術的實現(xiàn)過程。

2. 技術背景

markdown的基礎應用不再贅述，詳見筆者簡書專欄：http://www.lxweimin.com/nb/6041803。

本文采用的技術框架為：

看云是一個專業(yè)的markdown技術文檔、書籍的托管發(fā)布平臺，也有相應的手機客戶端。

關于看云平臺的使用方法，詳見http://help.kancloud.cn/41497。

mark

gitbook是一個國外的markdown書籍創(chuàng)作平臺，有相應的editor編輯器。gitbook的軟件及平臺本身即可實現(xiàn)技術文檔的撰寫發(fā)布，但網(wǎng)絡不暢通且不穩(wěn)定，不適合國內使用。此處僅采用gitbook編輯器軟件。

大型技術文檔的編輯發(fā)布，關鍵在于markd子文檔的集成，以及編譯方式的定義。其中的技術邏輯與LaTeX排版方式類似。

通過itbook創(chuàng)建的書籍項目，基本文件結構為：

mark

# Summary

* [引言](README.md)
* [理論基礎](理論基礎.md)
    * [導波控制方程](導波控制方程.md)
    * [導波頻散曲線分析](導波頻散曲線分析.md)
* [數(shù)值模擬](數(shù)值模擬.md)

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

注冊看云
http://www.kancloud.cn
下載gitbook
官方下載網(wǎng)站為：https://www.gitbook.com/editor/，但下載速度極慢，很不穩(wěn)定。
百度網(wǎng)盤下載更方便：鏈接：http://pan.baidu.com/s/1nuVG9dB 密碼：8hrc
安裝gitbook
安裝過程按照默認配置即可，沒有必要注冊gitbook

看云主要作為網(wǎng)上的分享、發(fā)布平臺，而文檔項目的內容編輯主要在本地電腦，通過gitbook實現(xiàn)。

如此即完成了基本的項目配置工作，后續(xù)主要進行內容的創(chuàng)作。

其中，introduction與README.md對應，是默認的必備文件，無法刪除。
First Chapter與chapter1.md對應，可以刪除。

構建自己的章節(jié)框架
按照一般的布局習慣，將introduction改為引言，First Chapter刪除。
按照寫作需求創(chuàng)建章，這里實際上相當于章的標題和每章引言。

mark
輸入文字內容后，gitbook會自動創(chuàng)建相應的markdown文件。

mark
創(chuàng)建具體的節(jié)內容

mark
獨立目錄創(chuàng)建
除了基本的markdown語法之外，看云支持在文檔首添加[toc]，生成子文檔的獨立目錄。效果如：

mark

每個markdown文件的內容實際上相互獨立，通過SUMMARY.md組織成整理。通過gitbook創(chuàng)建的內容可以生成默認的SUMMARY文件：

mark

其基本語法是markdown標準語法中，無序列表和超鏈接的結合，但此處的超鏈接指向文檔的子文件。：

* [引言](README.md)
* [理論基礎](理論基礎.md)

注意到：“理論基礎”是章標題（一級），而“導波控制方程”與“導波頻散曲線分析”為節(jié)標題（二級），可以手動調整邏輯層次。

mark