经验首页 前端设计 程序设计 Java相关 移动开发 数据库/运维 软件/图像 大数据/云计算 其他经验
当前位置:技术经验 » 软件/图像 » Git » 查看文章
使用gitbook快速搭建文档中心
来源:cnblogs  作者:三国梦回  时间:2023/10/23 8:59:28  对本文有异议

背景

在研发一个系统,主要给公司内部同事用,按理说,简单点的话,搞个使用文档就行了,但产品经理希望是做成一个文档中心,比如,你学习个新技术的时候,比如vue,一般有个在线的帮助文档,他的想法就是这种。

image-20231021154919586

我们就开始了调研,刚开始看了下wordpress(好多云服务器支持用这个来搭建网站),后面发现好复杂,我们只需要一个清爽的帮助文档而已;后面发现文档中心这种,主要分两类,一类是动态的,有数据库,有后台管理界面,可以在后台管理中去发布文档;一种是静态的,基本就是提供写好的markdown,然后部署到服务器上,用特定技术预先渲染成html,再利用nginx之类的指向这些html,一个静态文档中心就有了。

前一阵调研了一个叫gitbook的,属于静态方案,这里简单记录下搭建过程。

gitbook 简介

gitbook的官网是https://www.gitbook.com/,它官网主要是商业版本,就是个在线网站,你可以在里面写文档,体验还可以;

开源版本维护在github,https://github.com/GitbookIO/gitbook,文档也是在github维护:

https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md

目前,开源版本的发布包,最近一个版本是2018年10月,因为团队都去搞商业版本去了,这边就没维护了。

但是,gitbook做出来效果还可以,它也支持很多插件,由于gitbook是node开发的,所以插件就是各种npm包:

插件可以在npm官网查找,gitbook的插件都是有规范的,是gitbook-plugin-开头:

  1. https://www.npmjs.com/search?ranking=popularity&q=gitbook-plugin-

image-20231021160435536

gitbook做出来的网站的效果

示例1

https://handbook.enspiral.com/guides/blogging

image-20231021161050857

该网站的搜索效果是做不出来的,这个是对接了专门的搜索网站

对应的github:https://github.com/enspiral/handbook

示例2

https://tutorial.djangogirls.org/

github:https://github.com/DjangoGirls/tutorial

开源版本可以做到的搜索的效果:

image-20231021161422389

示例3

这边是一个中文站:

https://uprogrammer.cn/html5-cn/overview.html

image-20231021161757153

大体效果就上面那些,如果觉得还可以,就可以看看怎么搭建了。

gitbook的fork版本

gitbook的开源版本没怎么维护了,但是后面社区又有人接着维护,那就是honkit

https://github.com/honkit/honkit

  1. ?? HonKit is building beautiful books using Markdown - Fork of GitBook

这个到现在也还在维护,但是感觉搭建出来效果差不多,不知道优化了哪里,不过反正honkit也是支持那些老的gitbook的插件,可以考虑直接用honkit搭建。

安装过程

centos7.9 node安装

我之前搭建过一次,就是遇到一些小问题,所以降了版本,一路降到了node的v12:

https://nodejs.org/download/release/v12.3.0/

下载压缩包,解压,然后设置到/etc/profile

  1. vim /etc/profile
  2. export PATH=/root/upload/node-v12.3.0-linux-x64/bin:$PATH
  1. [root@VM-0-6-centos ~]# node -v
  2. v12.3.0
  3. [root@VM-0-6-centos ~]# npm -v
  4. 6.9.0

本来这次不想认怂,就用node v18,见招拆招,结果就报了下面那些glibc 、gcc版本过低的问题,然后搞了几个小时没搞好(我怕把环境搞坏了,用的本地虚拟机来编译glibc、gcc,结果gcc编了快2个小时了还没好,我也是服了,回头再战吧)

centos 7.9安装nodejs v18的一些问题

首先,node目前最新的长期支持版本是v18.18.2,但是,在centos7.9上,都是用不了的。可以看下面的具体报错,是node v18版本依赖了高版本的glic库,而这个库在centos 7.9上没有;同时,也需要安装高版本的gcc,才能运行不报错,而这个高版本的gcc在centos 7.9上也没有。

https://nodejs.org/en/download

image-20231021122811833

  1. tar -xJvf node-$VERSION-$DISTRO.tar.xz
  2. cd node-v18.18.2-linux-x64
  3. [root@node1 node-v18.18.2-linux-x64]# bin/npm
  4. node: /lib64/libm.so.6: version `GLIBC_2.27' not found (required by node)
  5. node: /lib64/libc.so.6: version `GLIBC_2.25' not found (required by node)
  6. node: /lib64/libc.so.6: version `GLIBC_2.28' not found (required by node)
  7. node: /lib64/libstdc++.so.6: version `CXXABI_1.3.9' not found (required by node)
  8. node: /lib64/libstdc++.so.6: version `GLIBCXX_3.4.20' not found (required by node)
  9. node: /lib64/libstdc++.so.6: version `GLIBCXX_3.4.21' not found (required by node)

安装并配置

https://github.com/cctvckl/markdown-sample

可以参考这里

就是一堆目录和markdown

image-20231021164128294

我这边上传到一个目录下:

  1. [root@VM-0-6-centos temp-doc]# ll
  2. total 20
  3. drwxr-xr-x 2 root root 4096 Oct 21 16:39 archive
  4. drwxr-xr-x 2 root root 4096 Oct 21 16:39 foundation
  5. drwxr-xr-x 2 root root 4096 Oct 21 16:39 money
  6. drwxr-xr-x 2 root root 4096 Oct 21 16:39 nodes
  7. drwxr-xr-x 2 root root 4096 Oct 21 16:39 working-groups
  8. [root@VM-0-6-centos temp-doc]# pwd
  9. /root/doctest/temp-doc
  10. [root@VM-0-6-centos temp-doc]#

然后安装官网:https://github.com/honkit/honkit

  1. 初始化:
  2. [root@VM-0-6-centos temp-doc]# npm init --yes
  3. Wrote to /root/doctest/temp-doc/package.json:
  4. {
  5. "name": "temp-doc",
  6. "version": "1.0.0",
  7. "description": "",
  8. "main": "index.js",
  9. "scripts": {
  10. "test": "echo \"Error: no test specified\" && exit 1"
  11. },
  12. "keywords": [],
  13. "author": "",
  14. "license": "ISC"
  15. }

安装依赖:

  1. npm install honkit --save-dev

image-20231021164806790

  1. [root@VM-0-6-centos temp-doc]# npx honkit init
  2. warn: no summary file in this book
  3. info: create README.md
  4. info: create SUMMARY.md
  5. info: initialization is finished

然后,提示我们,没有summary文件(相当于目录),帮我们建了一个,但是建的这个基本没法用:

  1. [root@VM-0-6-centos temp-doc]# ll
  2. total 112
  3. drwxr-xr-x 2 root root 4096 Oct 21 16:39 archive
  4. drwxr-xr-x 2 root root 4096 Oct 21 16:39 foundation
  5. drwxr-xr-x 2 root root 4096 Oct 21 16:39 money
  6. drwxr-xr-x 188 root root 4096 Oct 21 16:46 node_modules
  7. drwxr-xr-x 2 root root 4096 Oct 21 16:39 nodes
  8. -rw-r--r-- 1 root root 273 Oct 21 16:46 package.json
  9. -rw-r--r-- 1 root root 74464 Oct 21 16:46 package-lock.json
  10. -rw-r--r-- 1 root root 16 Oct 21 16:47 README.md
  11. -rw-r--r-- 1 root root 40 Oct 21 16:47 SUMMARY.md
  12. drwxr-xr-x 2 root root 4096 Oct 21 16:39 working-groups
  13. [root@VM-0-6-centos temp-doc]# cat SUMMARY.md
  14. # Summary
  15. * [Introduction](README.md)

这个文档,本来就是需要你自己手动建的,但这里可以先用我这边的,后边可以介绍,用插件根据文件夹那些来自动创建好SUMMARY文件

  1. [root@VM-0-6-centos handbook-main]# cat SUMMARY.md
  2. # Table of contents
  3. * [Introduction](README.md)
  4. * [Guides](guides/README.md)
  5. * [Assembly Sprint](guides/assembly-sprints.md)
  6. * [Blogging](guides/blogging.md)
  7. * [Conflict Resolution](guides/conflict-resolution.md)
  8. * [Comms Guidelines](guides/comms_guidelines.md)
  9. * [Contributing to the Handbook](guides/contributing.md)
  10. * [Content dusting](guides/content-dusting.md)
  11. * [Email accounts](guides/email_accounts.md)
  12. * [Enspiral Values](guides/values.md)
  13. * [Github for Beginners](guides/github_for_beginners.md)
  14. * [Newcomers](guides/newcomers.md)
  15. * [Onboarding](guides/onboarding.md)
  16. * [Ops processes](guides/ops_processes.md)
  17. * [Pods](guides/pods.md)
  18. * [Project Kitchens](guides/project_kitchen.md)
  19. * [Projects & Reports](guides/projects_reports.md)
  20. * [PR tips for humans](guides/press.md)
  21. * [Research](guides/research.md)
  22. * [Retreats](guides/retreats.md)
  23. * [Songs](guides/songs.md)
  24. * [Workshop Patterns](guides/workshop_patterns.md)
  25. * [Nodes](/nodes/README.md)
  26. * [Enspiral Europe](/nodes/enspiral-europe.md)
  27. * [Enspiral DAO](/nodes/enspiral-dao.md)
  28. * [Kumara Node](/nodes/kumara.md)
  29. * [Working Groups](working-groups/README.md)
  30. * [Comms](working-groups/comms.md)
  31. * [Gatherings](working-groups/gatherings.md)
  32. * [Enspiral Foundation Ltd](foundation/README.md)
  33. * [Constitution](foundation/constitution.md)
  34. * [Board of Directors](foundation/board.md)
  35. * [Ops Scope](foundation/ops-scope.md)
  36. * [Comms Role Scope](foundation/comms-role.md)
  37. * [Money](money/README.md)
  38. * [Collaborative Funding](money/collabfunding.md)
  39. * [Contributing Money](money/contributing-money.md)
  40. * [Financial Transparency](money/financial_transparency.md)
  41. * [Ventures](/ventures.md)
  42. * [Resources](resources.md)
  43. * [Archive](archive/README.md)

调试模式启动

  1. [root@VM-0-6-centos temp-doc]# npx honkit serve
  2. Live reload server started on port: 35729
  3. Press CTRL+C to quit ...
  4. info: >> Starting server ...
  5. info: 6 plugins are installed
  6. info: 6 explicitly listed
  7. info: plugin "livereload" is loaded
  8. info: plugin "highlight" is loaded
  9. info: plugin "search" is loaded
  10. info: plugin "lunr" is loaded
  11. info: plugin "fontsettings" is loaded
  12. info: plugin "theme-default" is loaded
  13. info: found 1 pages
  14. info: found 17 asset files
  15. info: >> generation finished with success in 0.3s !
  16. Serving book on http://localhost:4000

此时,通过访问ip:4000端口,就能看到效果,但我们实际部署,一般会编译成html,再通过nginx之类的,对外暴露成网站。

编译为html

其实在执行上面的npx honkit serve后,就生成了index.html和相关的资源文件,在当前目录的_book目录下:

image-20231021170724174

编译的命令:

  1. [root@VM-0-6-centos temp-doc]# npx honkit build
  2. info: 5 plugins are installed
  3. info: 5 explicitly listed
  4. info: plugin "highlight" is loaded
  5. info: plugin "search" is loaded
  6. info: plugin "lunr" is loaded
  7. info: plugin "fontsettings" is loaded
  8. info: plugin "theme-default" is loaded
  9. info: found 1 pages
  10. info: found 17 asset files
  11. info: >> generation finished with success in 0.3s !

通过nginx发布为网站

关键配置如下:

  1. server {
  2. listen 80;
  3. server_name localhost;
  4. location /{
  5. root /root/doctest/handbook-main/_book;
  6. }
  7. }

效果

访问 http://ip:80

image-20231021171403832

插件

自动生成SUMMARY.md

https://www.npmjs.com/package/gitbook-plugin-summary

Gitbook plugin to auto-generate SUMMARY.md

  1. npm i gitbook-plugin-summary --save
  2. 新建一个book.json文件,写入如下内容:
  3. {
  4. "plugins": [
  5. "summary"
  6. ]
  7. }
  8. [root@VM-0-6-centos temp-doc]# cat book.json
  9. {
  10. "plugins": [
  11. "summary"
  12. ]
  13. }
  14. [root@VM-0-6-centos temp-doc]# npx honkit build
  15. info: 6 plugins are installed
  16. info: 6 explicitly listed
  17. info: plugin "summary" is loaded
  18. info: plugin "highlight" is loaded
  19. info: plugin "search" is loaded
  20. info: plugin "lunr" is loaded
  21. info: plugin "fontsettings" is loaded
  22. info: plugin "theme-default" is loaded
  23. info: found 13 pages
  24. info: found 6 asset files
  25. gitbook-plugin-summary: SUMMARY.md generated successfully.
  26. info: >> generation finished with success in 1.7s !
  27. 上面可以看到,加载了summary插件

底部左右导航按钮

https://www.npmjs.com/package/gitbook-plugin-bottom-navigation

image-20231021172259238

  1. npm i gitbook-plugin-summary --save
  2. [root@VM-0-6-centos temp-doc]# cat book.json
  3. {
  4. "plugins": [
  5. "summary","bottom-navigation"
  6. ],
  7. "pluginsConfig": {
  8. "bottom-navigation": {
  9. "iconColor": "#3884FE",
  10. "titleColor": "#3884FE",
  11. "borderColor": "#3884FE"
  12. }
  13. }
  14. }
  15. npx honkit build

image-20231021172739063

  1. ## 默认插件

在执行npx honkit build的输出中,可以看到,还有一些默认插件:

  1. [root@VM-0-6-centos temp-doc]# npx honkit build
  2. info: 7 plugins are installed
  3. info: 7 explicitly listed
  4. info: plugin "summary" is loaded
  5. info: plugin "bottom-navigation" is loaded
  6. info: plugin "highlight" is loaded
  7. info: plugin "search" is loaded
  8. info: plugin "lunr" is loaded
  9. info: plugin "fontsettings" is loaded
  10. info: plugin "theme-default" is loaded

默认插件也是可以去掉的,可以换成社区里更好的,语法大家网上找一下就有了。

book.json参考

我这边的一份简单的配置:

  1. [root@VM-0-6-centos handbook-main]# cat book.json
  2. {
  3. "styles": {
  4. "website": "styles/website.css"
  5. },
  6. "plugins": ["bottom-navigation",
  7. "page-footer-ex", "collapsible-menu", "video", "page-treeview","page-toc-button" ],
  8. "pluginsConfig": {
  9. "page-treeview": {
  10. "copyright": "",
  11. "minHeaderCount": "2",
  12. "minHeaderDeep": "2"
  13. },
  14. "styles": {
  15. "website": "styles/website.css"
  16. },
  17. "page-toc-button": {
  18. "maxTocDepth": 2,
  19. "minTocSize": 2
  20. },
  21. "bottom-navigation": {
  22. "iconColor": "#3884FE",
  23. "titleColor": "#3884FE",
  24. "borderColor": "#3884FE"
  25. }
  26. },
  27. "variables": {
  28. "org": "Enspiral",
  29. "legalOrg": "Enspiral Foundation ltd"
  30. }
  31. }

参考

https://github.com/enspiral/handbook

http://dianyao.co/gitbook-notes/

https://www.npmjs.com/package/@dogatana/honkit-plugin-search-plus

https://honkit.netlify.app/examples

https://ylface.com/mac/249.html

https://github.com/Ynjxsjmh/gitbook-plugin-bottom-navigation

https://mp.weixin.qq.com/s/eD16_Vw7z6IYrLCs5-Stug

https://mp.weixin.qq.com/s/iL3lvaDkX1MLsk8JRJtA_w

https://mp.weixin.qq.com/s/Xc3OksVsL1GfomaiJi83sg

原文链接:https://www.cnblogs.com/grey-wolf/p/17779281.html

 友情链接:直通硅谷  点职佳  北美留学生论坛

本站QQ群:前端 618073944 | Java 606181507 | Python 626812652 | C/C++ 612253063 | 微信 634508462 | 苹果 692586424 | C#/.net 182808419 | PHP 305140648 | 运维 608723728

W3xue 的所有内容仅供测试,对任何法律问题及风险不承担任何责任。通过使用本站内容随之而来的风险与本站无关。
关于我们  |  意见建议  |  捐助我们  |  报错有奖  |  广告合作、友情链接(目前9元/月)请联系QQ:27243702 沸活量
皖ICP备17017327号-2 皖公网安备34020702000426号