Gitbook文档规范

#概要

##目的
为了规范文档管理工作，提高团队协作效率，输出高质量的文档，特制定本规范。本规范文档一经确认, 所有开发人员必须按本文档规范进行执行. 本规范如有不对或者不合适的地方请及时提出, 经讨论决定后方可更改.

范围

本规范适用于项目文档、API接口文档、使用说明文档、架构文档等

文档基本准则

符合Markdown标准, 结构要有层次感，逻辑清晰简洁

文档管理

使用git仓库对markdown文档进行管理
有两种方式：

跟随代码仓库一起管理，例如在项目的根目录下有一个docs目录里面放文档
单独创建 XX_doc的仓库来管理
至于选择哪种方式，可以择优而定。若是多个项目团队共同协作文档，建议选择第二种方式。

最终文档会使用gitbook在文档服务器进行展现，由文档最高管理员统一申请域名并部署

规范

项目文档

在项目（代码仓库）的根目录下必须有一个”docs”目录，该目录下主要是用来存放相关文档

文档目录结构

文档仓库根目录必须包含以下几个文件

book.json 可选 gitbook的一些配置，比如可以指定展现的模版主题
README.md 必须写一些相关介绍
usage.md 必须写该项目或框架的使用说明
SUMMARY.md 必须主要是book目录，每添加一个文档都需要在这个文件中添加目录

book.json的举例如下

{
    "title" : "斗米客户端研发部文档",
	"language" : "zh-hans",
	"plugins": ["theme-comscore",
                "-sharing",
	            "-search",
                "-lunr",
	            "search-plus",
	            "splitter",
                "expandable-chapters-small",
                "-highlight",
                "prism",
                "prism-themes",
                "anchor-navigation-ex"
                
	           ],
    "pluginsConfig": {
        "prism": {
            "css": [
                "prism-themes/themes/prism-base16-ateliersulphurpool.light.css"
            ]
        },
        "anchor-navigation-ex": {
            "showLevel": true,
            "associatedWithSummary": true,
            "mode": "float", 
            "float": {
                "showLevelIcon": false,
                "level1Icon": "fa fa-hand-o-right",
                "level2Icon": "fa fa-hand-o-right",
                "level3Icon": "fa fa-hand-o-right"
            },
            "pageTop": {
                "showLevelIcon": false,
                "level1Icon": "fa fa-hand-o-right",
                "level2Icon": "fa fa-hand-o-right",
                "level3Icon": "fa fa-hand-o-right"
                }
        },
        "theme-default": {
            "showLevel": false
        }
    }
}

针对`SUMMARY.md`举例如下

# Summary
* [介绍](README.md)
* [使用说明](usage.md)
* [组件拆分最佳实践](best.md)
* [grain配置](config.md)
* [javascript API](api.md)
	* [缓存类API](api/cache.md)
	* [位置类API](api/location.md)
	* [信息类API](api/clientInfo.md)
	* [安全类API](api/safety.md)
	* [定制界面类API](api/clientUi.md)
	* [原生功能类API](api/widget.md)
	* [自定义API](api/customize.md)

Markdown书写规范

1. 段落与段落之间空一行表示。
   分节的时候可以多空一行。单个回车视为空格，连续回车才是换行。（行尾加两个空格，可以段内强制换行，一般用户可以忽略。）
2. 其实在网络上你可以完全抛弃开头空两格的习惯，代之以段落之间空一行的习惯。如果只要要开头空两格，那么可以输入&ensp;来表示一个空格，&emsp;为两个。或者使用输入法切换到全角，双击空格键。
3. 标题：# 一级标题
        “#”之后最好加一个空格，这在md单向标记中都最好使用
        也可以把”=“写在标题（H1）下面的一行，表示上面一行的文字为标题，”-“写在下面便是小标题或是节标题（H2）。
4. 加粗，斜体：**加粗**，*斜体*，***粗斜体***
5. 引用：>
6. 行内源代码：‘代码'。行的开头空四个空格，缩进内容视为代码块。代码块也可以用’‘’代码‘’‘来完成。当然简单的用'代码'也可以显示。
7. 删除线：~~删除~~
8. 层次（也就是类似目录列表的东西）：“*” 后面要加空格，这是必须的，除了 *，还可以使用 + 或者 -。
        1. 第一节
        2. 第二节
            * 第一小节（推荐每层次缩进四个空格）
                * 小小节 1
                * 小小节 2
            * 第二小节
9. 链接，图片：[想要显示的文字](链接,"Title")，![（图片说明）](图片链接)。段落内使用的时候左右各空一格，除非是使用列表的时候。
此外，还可以以索引方式把url都列在文章的最后，例如这样：
[文字][1]
[1]: 链接（不要忘记冒号后面的空格，title的写法与上类似）
10. 分割线：---，上下各空一行,也可以用***，其实只要三个以上，随便你怎么写。
11. 其他：
        [链接标题][null-link]，可以生成一个伪链接样式，也就是存在链接的样式，但没有实质的链接。更高级的链接写法：[文字][hover]
                           [hover]:链接"悬停文字"
        图片链接：
        [![][jane-eyre-pic］[jane-eyre-douban]
        [jane-eyre-pic]: http://img3.douban.com/mpic/s1108264.jpg
        [jane-eyre-douban]: http://book.douban.com/subject/1141406/
        若要在图片下线是说明：{ImagCap}说明{/ImgCap}
12. 跟其他的编程语言一样，利用转意字符”/“就可以输出”[“这类符号

范围