GitBook 告别文档共享烦恼

GitBook

  GitBook 提供以下功能。

  • 支持 markdown 语法
  • 自动构建文档网站
  • 丰富的插件来拓展网站,比如:搜索,代码高亮等
  • 支持 git 进行文档项目管理

什么是 GitBook

  GitBook 是一个文档编辑工具。它的功能类似金山的 WPS,微软的 Office 中的 Word 文档编辑工具。它可以用来写文档、建表格、插图片、生成 pdf 。虽然这些功能不一定有 WPS、Office 做得好,但是它可以用文档生成一个网站,让更多的人了解到你书写的内容。从此,不再为共享文档给他人后,如何时时同步而烦恼。实例效果如下:
这里写图片描述

GitBook 官网注册登录后,可在线创建、编辑和发布文档。线下提供离线编辑工具 GitBook Editor。但是本文档主要讲解的是 ,如何利用 GitBook 的命令行工具 gitbook-cli 来创建、预览及发布文档。

安装 gitbook-cli

NodeJs

  安装 NodeJs 是因为我们要使用其提供的 npm 包管理工具来下载安装 gitbook-cli。从 NodeJs 官网 下载最新版本安装即可(版本要求 V4.0.0 及以上)。

安装 gitbook-cli

  运行以下命令进行安装

npm install gitbook-cli -g

gitbook init 项目初始化

  首先新建如下目录结构

README.md 和 SUMMARY.md 是两个必须文件。
- README.md: 是对书籍的简单介绍

鼎盛云开放平台 H5 接口文档
  • SUMMARY.md:是书籍的目录结构
# Summary

* [Introduction](README.md)
* [1、接口规则](chapter1/README.md)
    * [1.1、协议规则](chapter1/section1.1.md)
    * [1.2、公共参数](chapter1/section1.2.md)
    * [1.3、其它说明](chapter1/section1.3.md)
        * [1.3.1、其它说明](chapter1/section1.3.1.md)
* [2、用户](chapter2/README.md)
    * [2.1、手机号查询用户注册状态](chapter2/section2.1.md)
    * [2.2、用户注册-短信下发](chapter2/section2.2.md)
    * [2.3、用户注册-短信验证](chapter2/section2.3.md)
    * [2.4、验证交易密码](chapter2/section2.4.md)
    * [2.5、是否关联身份信息-手机号](chapter2/section2.5.md)
    * [2.6、设置账单日](chapter2/section2.6.md)

注意星号”*” 后面有个空格,忽略此会直接导致文档生成失败。

创建完这两个文件后,在文档根目录运行一下命令,初始化项目(gitbook 会帮我们生成 SUMMARY.md 中的目录结构)

gitbook init

gitbook serve 编辑预览

  书籍目录结构创建完成以后,就可以使用命令 gitbook serve 来预览书籍了。打开浏览器,输入http://localhost:4000查看书籍效果。当然,文档的具体内容,就有待自己去添加了。建议使用 markdown 语法,这里为小白提供一个markdown 简单教程;

gitbook build 发布图书

  通过执行 gitbook build 命令,gitbook 会在根目录下面生成一个编译打包后的文件 _book 里面便是我们文档编译后生成的 html 网页。后面便是,通过 ngnix 托管,让其在互联网上可见。

Glossary 词汇解释

  词汇表文件,默认对应根目录下的 GLOSSARY.md 。该文件主要存储词汇信息,如果在其它页面中出现了该文件中的词汇,鼠标放在词汇上会给出词汇解释。
  Glossary 文件的格式如下所示:

## API
接口说明文档

## Markdown
排版语言,程序员专属

这里是两个 ## 。

book.json 文档配置信息说明文件

  存放在根目录,记录文档项目的一些说明信息,及最后项目打包的配置信息。格式如下:

{
    title:"文档名称",
    author:"作者1;作者2",
    description:"文档描述",
    language:"使用的语言,英语、简体中国等",
    gitbook:">=3.2.2",  // gitbook 的版本
    root:".",// 指定存放 GitBook 文件的根目录
    links:"左侧边栏添加链接" ,
    styles:"指定打包生成网页的样式",
    plugins:"指定打包生成网页需要使用的插件",
    pluginsConfig:"配置插件的属性",
}

language

  GitBook 使用的语言,简体中文配置如下:

"language":"zh-hans"

  在左侧导航栏添加链接信息

"links":{
    "sidebar":{
        "Home":"http://localhost:4000"
    }
}

styles

  自定义页面样式,默认情况下各 generator 对应的 css 文件

"styles":{
    "website":"styles/website.css",
    "ebook":"styles/ebook.css",    
    "pdf":"styles/pdf.css",
    "mobi":"styles/mobi.css",
    "epub":"styles/epub.css",
}

plugins

  配置使用的插件

"plugins":[
    "disqus"
]

添加新插件之后,需要运行 gitbook installl 来安装新插件
GitBook 默认带有 5 个插件 highlightsearchsharingfont-settingslivereload。如果要去除自带的插件,可以在插件名称前面加 - 如下:

"plugins":[
    "-search"
]

更多可选插件,可在插件官网查看。常见插件使用

pluginsConfig

  配置插件的属性

"pluginsConfig":{
    "fontsettings":{
        "theme":"sepia",
        "family":"serif"
        "size":1
    }
}
展开阅读全文

没有更多推荐了,返回首页