使用gitbook快速搭建文檔中心

背景

在研發一個系統,主要給公司內部同事用,按理說,簡單點的話,搞個使用文檔就行了,但產品經理希望是做成一個文檔中心,比如,你學習個新技術的時候,比如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-開頭:

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

📖 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

vim /etc/profile
export PATH=/root/upload/node-v12.3.0-linux-x64/bin:$PATH
[root@VM-0-6-centos ~]# node -v
v12.3.0
[root@VM-0-6-centos ~]# npm -v
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

tar -xJvf node-$VERSION-$DISTRO.tar.xz
cd node-v18.18.2-linux-x64

[root@node1 node-v18.18.2-linux-x64]# bin/npm
node: /lib64/libm.so.6: version `GLIBC_2.27' not found (required by node)
node: /lib64/libc.so.6: version `GLIBC_2.25' not found (required by node)
node: /lib64/libc.so.6: version `GLIBC_2.28' not found (required by node)
node: /lib64/libstdc++.so.6: version `CXXABI_1.3.9' not found (required by node)
node: /lib64/libstdc++.so.6: version `GLIBCXX_3.4.20' not found (required by node)
node: /lib64/libstdc++.so.6: version `GLIBCXX_3.4.21' not found (required by node)

安裝並配置

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

可以參考這裏

就是一堆目錄和markdown

image-20231021164128294

我這邊上傳到一個目錄下:


[root@VM-0-6-centos temp-doc]# ll
total 20
drwxr-xr-x 2 root root 4096 Oct 21 16:39 archive
drwxr-xr-x 2 root root 4096 Oct 21 16:39 foundation
drwxr-xr-x 2 root root 4096 Oct 21 16:39 money
drwxr-xr-x 2 root root 4096 Oct 21 16:39 nodes
drwxr-xr-x 2 root root 4096 Oct 21 16:39 working-groups
[root@VM-0-6-centos temp-doc]# pwd
/root/doctest/temp-doc
[root@VM-0-6-centos temp-doc]# 

然後安裝官網:https://github.com/honkit/honkit

初始化:
[root@VM-0-6-centos temp-doc]# npm init --yes
Wrote to /root/doctest/temp-doc/package.json:

{
  "name": "temp-doc",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

安裝依賴:

npm install honkit --save-dev

image-20231021164806790

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

然後,提示我們,沒有summary文件(相當於目錄),幫我們建了一個,但是建的這個基本沒法用:

[root@VM-0-6-centos temp-doc]# ll
total 112
drwxr-xr-x   2 root root  4096 Oct 21 16:39 archive
drwxr-xr-x   2 root root  4096 Oct 21 16:39 foundation
drwxr-xr-x   2 root root  4096 Oct 21 16:39 money
drwxr-xr-x 188 root root  4096 Oct 21 16:46 node_modules
drwxr-xr-x   2 root root  4096 Oct 21 16:39 nodes
-rw-r--r--   1 root root   273 Oct 21 16:46 package.json
-rw-r--r--   1 root root 74464 Oct 21 16:46 package-lock.json
-rw-r--r--   1 root root    16 Oct 21 16:47 README.md
-rw-r--r--   1 root root    40 Oct 21 16:47 SUMMARY.md
drwxr-xr-x   2 root root  4096 Oct 21 16:39 working-groups
[root@VM-0-6-centos temp-doc]# cat SUMMARY.md 
# Summary

* [Introduction](README.md)

這個文檔,本來就是需要你自己手動建的,但這裏可以先用我這邊的,後邊可以介紹,用插件根據文件夾那些來自動創建好SUMMARY文件

[root@VM-0-6-centos handbook-main]# cat SUMMARY.md 
# Table of contents

* [Introduction](README.md)
* [Guides](guides/README.md)
  * [Assembly Sprint](guides/assembly-sprints.md)
  * [Blogging](guides/blogging.md)
  * [Conflict Resolution](guides/conflict-resolution.md)
  * [Comms Guidelines](guides/comms_guidelines.md)
  * [Contributing to the Handbook](guides/contributing.md)
  * [Content dusting](guides/content-dusting.md)
  * [Email accounts](guides/email_accounts.md)
  * [Enspiral Values](guides/values.md)
  * [Github for Beginners](guides/github_for_beginners.md)
  * [Newcomers](guides/newcomers.md)
  * [Onboarding](guides/onboarding.md)
  * [Ops processes](guides/ops_processes.md)
  * [Pods](guides/pods.md)
  * [Project Kitchens](guides/project_kitchen.md)
  * [Projects & Reports](guides/projects_reports.md)
  * [PR tips for humans](guides/press.md)
  * [Research](guides/research.md)
  * [Retreats](guides/retreats.md)
  * [Songs](guides/songs.md)
  * [Workshop Patterns](guides/workshop_patterns.md)
* [Nodes](/nodes/README.md)
        * [Enspiral Europe](/nodes/enspiral-europe.md)
        * [Enspiral DAO](/nodes/enspiral-dao.md)
        * [Kumara Node](/nodes/kumara.md)
* [Working Groups](working-groups/README.md)
  * [Comms](working-groups/comms.md)
  * [Gatherings](working-groups/gatherings.md)
* [Enspiral Foundation Ltd](foundation/README.md)
  * [Constitution](foundation/constitution.md)
  * [Board of Directors](foundation/board.md)
  * [Ops Scope](foundation/ops-scope.md)
  * [Comms Role Scope](foundation/comms-role.md)
* [Money](money/README.md)
  * [Collaborative Funding](money/collabfunding.md)
  * [Contributing Money](money/contributing-money.md)
  * [Financial Transparency](money/financial_transparency.md)
* [Ventures](/ventures.md)
* [Resources](resources.md)
* [Archive](archive/README.md)

調試模式啓動

[root@VM-0-6-centos temp-doc]# npx honkit serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: >> Starting server ... 
info: 6 plugins are installed 
info: 6 explicitly listed 
info: plugin "livereload" is loaded
info: plugin "highlight" is loaded
info: plugin "search" is loaded
info: plugin "lunr" is loaded
info: plugin "fontsettings" is loaded
info: plugin "theme-default" is loaded
info: found 1 pages 
info: found 17 asset files 
info: >> generation finished with success in 0.3s ! 
Serving book on http://localhost:4000

此時,通過訪問ip:4000端口,就能看到效果,但我們實際部署,一般會編譯成html,再通過nginx之類的,對外暴露成網站。

編譯爲html

其實在執行上面的npx honkit serve後,就生成了index.html和相關的資源文件,在當前目錄的_book目錄下:

image-20231021170724174

編譯的命令:

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

通過nginx發佈爲網站

關鍵配置如下:

 server {
        listen       80;
        server_name  localhost;

        location /{
            root  /root/doctest/handbook-main/_book;
        }
    }

效果

訪問 http://ip:80

image-20231021171403832

插件

自動生成SUMMARY.md

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

Gitbook plugin to auto-generate SUMMARY.md

npm i gitbook-plugin-summary --save

新建一個book.json文件,寫入如下內容:
{
  "plugins": [
    "summary"
  ]
}

[root@VM-0-6-centos temp-doc]# cat book.json 
{
  "plugins": [
    "summary"
  ]
}

[root@VM-0-6-centos temp-doc]# npx honkit build
info: 6 plugins are installed 
info: 6 explicitly listed 
info: plugin "summary" is loaded
info: plugin "highlight" is loaded
info: plugin "search" is loaded
info: plugin "lunr" is loaded
info: plugin "fontsettings" is loaded
info: plugin "theme-default" is loaded
info: found 13 pages 
info: found 6 asset files 
gitbook-plugin-summary: SUMMARY.md generated successfully.
info: >> generation finished with success in 1.7s ! 

上面可以看到,加載了summary插件

底部左右導航按鈕

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

image-20231021172259238

npm i gitbook-plugin-summary --save

[root@VM-0-6-centos temp-doc]# cat book.json 
{
  "plugins": [
    "summary","bottom-navigation"
  ],
  "pluginsConfig": {
   "bottom-navigation": {
      "iconColor": "#3884FE",
      "titleColor": "#3884FE",
      "borderColor": "#3884FE"
    }
  }
}

npx honkit build

image-20231021172739063

## 默認插件

在執行npx honkit build的輸出中,可以看到,還有一些默認插件:

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

默認插件也是可以去掉的,可以換成社區裏更好的,語法大家網上找一下就有了。

book.json參考

我這邊的一份簡單的配置:

[root@VM-0-6-centos handbook-main]# cat book.json 
{
  "styles": {
    "website": "styles/website.css"
  },
  "plugins": ["bottom-navigation",
    "page-footer-ex", "collapsible-menu", "video", "page-treeview","page-toc-button"  ],
  "pluginsConfig": {
        "page-treeview": {
            "copyright": "",
            "minHeaderCount": "2",
            "minHeaderDeep": "2"
        },
        "styles": {
            "website": "styles/website.css"
        },
"page-toc-button": {
            "maxTocDepth": 2,
            "minTocSize": 2
           },
"bottom-navigation": {
      "iconColor": "#3884FE",
      "titleColor": "#3884FE",
      "borderColor": "#3884FE"
    }
  },
  "variables": {
    "org": "Enspiral",
    "legalOrg": "Enspiral Foundation ltd"
  }
}

參考

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

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章