gitbook使用教程(与github关联)

麹正业
2023-12-01
gitbook是一款开源项目,用于生成、管理文档。在我所用到的场景中,一般是用于做项目的文档管理,如开发者文档、说明文档、用户手册等等。一般在现有的gitbook使用方法教程中,都是教你如何生成一个自己的文档。但是在我所面临的场景,都是给社区的项目做一个公共的文档,大家都可以去访问,去提交更新。因此本文档解决的问题是:

创建organization社区项目的文档,并且自动与gitbook关联,任何人可以像贡献代码一样贡献文档


在github创建book的repository

在个人github账户创建一个项目(在本文档中命名为testGitbook)。这个repository作为以后创建的文档的仓库,用于像代码一样管理文档。

在gitbook创建book

  • 进入www.gitbook.com
    用github账户登陆gitbook

  • 创建组织,
    组织命名为github上的organization的名字(在本文档中命名为testOrganization)

  • 新建文档。
    新建一个文档,在创建的时候注意,选择所属者为组织,确保访问地址为https://testOrganization.gitbooks.io//

设置gitbook

  • 点击testGitbook,选择settings
  • 选择Github选项,add Hook。如果上面显示失败,就手动添加到github,使得本book和github那个项目关联。

手动添加hook方法:复制Webhook URL,点击check webhook,跳转至github。在github中新建hook,在其中将刚才复制的URL粘贴到里面,保存即可。

移交本文档的git仓库

此时该book已经和github中的项目关联。更新任意一边,两边都能更新。我们可以像更新代码一样更新文档。

但是因为我们所需要达到的效果是,这个项目是organization中的一个项目。其他人可以fork这个文档的项目,并且可以提交pull request,进行文档的贡献。但是这个项目现在还是在我们个人的仓库里面。因此需要将此项目移交给organization。

  • 在github中,点击该文档的settings
  • Options->Transfer ownership,将文档项目移交给organization

至此,gitbook完成。可以更新organization中该book的仓库的内容,会自动更新book。在访问文档地址的时候会看到更新。

 类似资料: