基于GitBook的API文档管理

关于GitBook

  • GitBook是一种电子书的编写和发布解决方案，于2014年中由两个联合创始人Samy Pessé和Aaron O'Mullan创立。
  • 主要产品：
    1. https://www.gitbook.com 官网网站，提供会员注册登录和在线电子书管理和发布功能。
    2. https://www.gitbook.com/editor 电子书编辑器，支持Mac、Windows和Linux操作系统，方便的可视化IDE，用于创建、编辑和管理GitBook电子书，并且支持仓库同步。
    3. https://github.com/GitbookIO/gitbook 基于node.js的命令行工具，功能和Editor基本一致，但是支持GitBook的本地导出，也是对于开发者最方便的使用途径。（网站和开源社区搜索最多的关键词也是它）

使用步骤

  1. 登录GitBook官网，注册帐号。

  2. 下载并安装GitBook Editor工具，使用注册帐号登录。 gitbook_editor_login gitbook_editor_main

  3. 创建在线或离线电子书，然后编辑并同步到GitBook仓库或指定的远程仓库。 gitbook_editor_edit

  4. 同步成功后可以在网站上找到编写好的电子书，可以进行在线预览或者导出成PDF等格式。如果离线的电子书也可以直接使用命令行工具进行导出等操作。

    • 网页操作

      gitbook_website

    • 在线预览

      gitbook_webview

    • PDF导出

      gitbook_pdfview

    • 本地导出HTML

      1.切换到GitBook工作目录，并且通过build命令打包HTML

      gitbook_build

      2.生成成功可以看到成功输出的_book目录

      gitbook_build_dir

      3.打开index.html就可以离线方式预览HTML版本的GitBook了

      gitbook_build_preview

注意事项和问题

  • GitBook的帐号默认为个人，创建的电子书也都是个人拥有和管理。如果需要多人管理则需要创建组织并授权多人管理GitBook。（组织帐号如果想要发布Private的Book需要升级到付费帐号，最低为7美元每个月, 具体如下）

    • 多人授权

      gitbook_org_member

    • 产品定价

      gitbook_price

  • 离线导出eBook格式（PDF、ePub，Mobi）需要安装ebook-convert插件才可以调用命令。相关资料如下：

总结

  • GitBook本身是基于Markdown的文件组织形式，电子书的目录结构都存储在SUMMARY.md文件里。简而言之，GitBook格式就是一个Git仓库包含两个必须的文件（README.md and SUMMARY.md.）

  • 因为结构简单轻便，又采用了简洁的Markdown语言，所以具有非常灵活和可API化的特性。结合Git等协作工具使用更具优势。