使用 GitBook

an 「 Heroku for books」

Posted on November 16, 2016

简介

主页: https://www.gitbook.com/

The platform GitBook.com is like an “Heroku for books”: you can create a book on it (public, or private) and update it using git push.

常见问题: https://help.gitbook.com/


使用

Node.js 的命令行工具

  • 安装: npm install gitbook-cli -g

  • 初始化: gitbook init gitbook init ./directory

    如果有SUMMARY.md, 会根据SUMMARY.md创建相应目录和文件

  • 构建: gitbook build 输出到_book/

  • 构建并启动服务: gitbook serve gitbook serve --port 4000

  • 配置文件: book.json

    https://toolchain.gitbook.com/config.html

通过本地git管理git book

https://help.gitbook.com/books/how-can-i-use-git.html

  • gitbook 对应的https url: https://git.gitbook.com//.git

  • credentials: 支持用户名密码, 以及TOKEN方式

  • 创建token: https://www.gitbook.com/@/settings/tokens

  • 将创建的token保存到本机:

    % vi ~/.netrc
    machine git.gitbook.com
      login USERNAME-or-EMAIL
      password API-TOKEN-or-PASSWORD
    
  • 本地创建gitbook后再推送到gitbook

    按照格式创建git仓库, 然后注意增加远程即可:

    git remote add origin https://git.gitbook.com//.git

  • git 方式访问时, 总是报错cannot resolve git.gitbook.com: Unknown host

    解决办法: 翻墙

    .gitbook.com/* 加入 Shadowsocks 的 user-rule.txt

和github绑定

https://help.gitbook.com/github/can-i-host-on-github.html

  • 在gitbook的account’s settings页面对关联的github账号授权
  • 在github上新建一个对应的repo
  • 在gitbook的book配置页面: www.gitbook.com/book/{user_name}/{book_name}/settings/github 选择github的repo, 点击同步
  • 在github上关联webhook, webhook 使得github的push会自动通知gitbook, 这样gitbook也会拿到更新. 这一步我测试是自动完成的

    同时通过gitbook的修改, 会自动同步到github上去, 自动生成comment, 非常方便


插件

  • 已有插件: https://plugins.gitbook.com/

  • 配置:

    % book.json
    
    {
        "plugins": ["[email protected]", "anotherPlugin"]
        "pluginsConfig": {
           anotherPlugin: {...}  具体插件配置
         }
    }
    
  • 安装: gitbook install

    插件安装在node_modules/


其他