用GitBook制作自己的網(wǎng)頁版電子書

前言

幾年前閱讀過其他人用GitBook創(chuàng)建的文檔，可以直接在瀏覽器中打開，頁面干凈整潔，非常清爽，至今印象深刻。

GitBook非常適合用來為個人或團隊制作文檔，對于我這種偶爾寫博客的人群來說，GitBook可以說是一款神器。我后續(xù)打算用GitBook來整理一些可以歸納到一個系列的內(nèi)容，所以我先研究了GitBook。

關(guān)于GitBook

先看看GitBook的“自我介紹”。（來自GitBook官網(wǎng)：https://docs.gitbook.com/readme）

GitBook is a platform for capturing and documenting technical knowledge — from product docs, to internal knowledge bases and APIs.
GitBook是一個捕捉和記錄技術(shù)知識的平臺——從產(chǎn)品文檔到內(nèi)部知識庫和api。
We want to help teams to work more efficiently with a simple but powerful platform that helps them share their knowledge.
我們希望通過一個簡單但功能強大的平臺幫助團隊更高效地工作，幫助他們分享知識。
Our mission is to make a user-friendly and collaborative product for everyone to create, edit and share knowledge through documentation.
我們的使命是制作一個用戶友好的協(xié)作產(chǎn)品，讓每個人都可以通過文檔創(chuàng)建、編輯和共享知識。

我對GitBook的介紹。

正如GitBook官網(wǎng)的介紹那樣，它可以用來寫文檔，記錄和分享知識，還可以用來記錄API等。根據(jù)我的了解，GitBook有以下特點：

• GitBook是開源且免費的（https://github.com/GitbookIO/gitbook）
• GitBook可以在本地離線生成文檔，分享給他人使用
• GitBook可以托管文檔，支持直接用GitHub賬號登錄，還支持贊賞等豐富的功能
• GitBook使用Markdown語法，用過Markdown可以直接上手
• GitBook支持轉(zhuǎn)換PDF、HTML等格式，方便生成電子書或靜態(tài)網(wǎng)頁

這些特點展現(xiàn)了GitBook非常實用的功能，完美適用于制作個人電子書。我之前看過的文件就是由GitBook生成的靜態(tài)網(wǎng)頁，生成可交互的靜態(tài)網(wǎng)頁就是我使用GitBook的核心需求。那如何使用GitBook呢？

安裝GitBook

GitBook 需要依賴于 Node.js，因此要先下載 Node.js 并安裝。本文是在 Windows 上安裝，Linux 和 Mac 安裝原理相似。

1. 安裝Node.js

Node.js下載地址： https://nodejs.org/en/download

這里需要注意，Node.js和GitBook之間可能會有兼容問題，不建議安裝最新版本的Node.js，我安裝的Node.js版本是v16.20.2（其他版本我沒有逐一嘗試，如果安裝過程中遇到很難解決的問題，可以卸載換其他版本）。

先進入Node.js下載頁面：

下拉到頁面下方，找到 Previous Releases（以往的版本）：

進入頁面后點擊需要的版本下載:

按照慣例，一般都是安裝偶數(shù)大版本號的版本。安裝過程很簡單，下載完成后，雙擊打開下載的安裝文件，一直點擊下一步直到安裝完成。

完成后打開命令行，輸入 node -v （v字母小寫），能返回Node.js的版本號即說明安裝成功。

2. 安裝GitBook

安裝完Node.js后，打開命令行，輸入 npm install -g gitbook-cli 安裝GitBook。命令執(zhí)行可能需要幾分鐘時間，請耐心等待。這個步驟如果遇到墻，可以換一下npm的國內(nèi)鏡像源，自己網(wǎng)上搜一下如何配置。

npm install -g gitbook-cli

命令執(zhí)行完后驗證是否安裝成功，輸入 gitbook -V （V字母大寫），能返回GitBook的版本號即說明安裝成功。

使用 gitbook 命令，可能會遇到如下報錯。

報錯信息：cb.apply is not a function ，這個問題是 polyfills.js 文件中的 287 行報錯了。解決這個問題，需要修改 polyfills.js 文件。復制報錯的文件路徑，找到 polyfills.js 文件并打開（可以用任何文本編輯器打開），注釋掉如下三行代碼（前面加雙斜線或直接快捷鍵注釋）就可以解決。

安裝不同版本，這三行代碼的具體行數(shù)可能會有差異，我的是 62-64 行。

此外，還可能會遇到如下報錯。

報錯信息：Error: Failed to parse json. Unexpected token ‘u’ at 1:1。這是代碼解析json出錯，但不知道具體哪個位置。

遇到這個問題，需要先將 Node.js 的版本降低，再重新安裝 GitBook 。比如我安裝最新版 Node.js v20.10.0，就會報這個錯，換成 v16.20.2 后無此問題。

過程中如果需要卸載 Node.js ，Windows 可以打開控制面板卸載，如果需要卸載 GitBook 則在命令行執(zhí)行 npm uninstall gitbook-cli -g 。

使用GitBook

1. 初始化GitBook

GitBook 安裝完成后，你可以在本電腦的任意位置使用。先創(chuàng)建一個項目文件夾，如我在桌面創(chuàng)建一個 GitBookDemo 文件夾，進入這個目錄，執(zhí)行命令 gitbook init 初始化項目。

執(zhí)行完后會自動創(chuàng)建目錄文件 SUMMARY.md 和 README.md 文件。這兩個文件都是 Markdown 格式的文件，要修改這兩個文件需要安裝 Markdowm 編輯器，如 MarkdownPad （只支持Windows）、Typora（支持所有OS）等，當然也可以不單獨安裝，VSCode、PyCharm、Sublime等程序員常用編輯器都可以支持 Markdown 格式編輯（如果沒有自帶裝個插件即可）。

2. 編輯電子書內(nèi)容

README.md 文件中可以寫一些電子書的說明介紹，SUMMARY.md 用于搭建電子書的目錄結(jié)構(gòu)。以本文內(nèi)容為例，可以先按照如下格式搭建好目錄。

定義目錄或章節(jié)的格式是 *[]() ，中括號中是頁面顯示內(nèi)容，小括號中是各章節(jié)的內(nèi)容文件，也都是用 md 格式。如果需要多級目錄，使用縮進控制。

搭建好目錄，在 GitBookDemo 中創(chuàng)建各章節(jié)的文件，輸入需要的內(nèi)容保存。

如果電子書中需要插入圖片，先準備好圖片，然后用 md 語法添加。如在 GitBookDemo 中新建一個 Images 文件夾用于存放準備的圖片。添加圖片的格式是 ![]()， 中括號中是圖片描述，可以為空，小括號中是圖片的相對路徑，如 Images/001.png 。

3. 生成電子書

內(nèi)容完成后，執(zhí)行 gitbook build 命令生成靜態(tài)網(wǎng)頁版電子書，如果需要生成PDF格式的電子書，則執(zhí)行 gitbook pdf 命令。

gitbook build 執(zhí)行成功后，會在項目目錄下生產(chǎn)一個 _book 文件夾，這個文件夾就是生成的電子書文件。進入 _book 目錄，用瀏覽器打開 index.html 文件就可以使用電子書了。

使用時如果章節(jié)不能跳轉(zhuǎn)，需要找到 _book/gitbook/theme.js 文件，在文件中 Ctrl+F 搜索 if(m)for(n.handler&& ，將 if(m) 改成 if(false) ，然后關(guān)掉 index.html 重新打開。

如果從章節(jié)頁面點擊簡介（README.md文件）時跳轉(zhuǎn)到了 _book 的上一級目錄，則需要修改每個章節(jié)的 html 文件中的跳轉(zhuǎn)鏈接，將 ./ 修改成 ./index.html 。

除了用 gitbook build 構(gòu)建生成結(jié)果，在編輯過程中，還可以隨時執(zhí)行 gitbook serve 命令(注意不是server) 啟動本地Web服務(wù)，在瀏覽器通過 http://localhost:4000 預覽電子書。

要關(guān)閉 gitbook serve 可以在終端使用快捷鍵 Ctrl+C，如果這樣關(guān)不掉，端口被占用，無法重新啟動 gitbook serve。此時新打開一個命令行窗口，執(zhí)行 netstat -ano|findstr 35729 查看端口的 PID，然后執(zhí)行 taskkill -F -PID 123456(例如查到的PID是123456) 殺掉進程。

4. 插件安裝

完成前面的內(nèi)容，已經(jīng)能成功生成電子書了，如果還需要更多的功能，可以安裝 GitBook 的插件。

在項目目錄下新建一個 book.json 文件，然后在 book.json 文件中寫入需要安裝的插件，以我需要使用的目錄折疊和回到頂部為例。

book.json:

{
    "plugins": [
        "expandable-chapters",
        "back-to-top-button"
    ]
}

準備好 book.json 后，在命令行執(zhí)行 gitbook install 命令安裝插件，安裝完成后重新 gitbook build 生成電子書，插件功能就會生效。

需要更多插件，可以到 GitBook 的官網(wǎng)查找。如果要禁用插件，則在 book.json 中的插件名前加一個橫杠，如要禁用目錄折疊功能就將 expandable-chapters 改成 -expandable-chapters 。

此外，book.json 中除了可以配置插件信息，還可以配置很多其他信息，如自定義樣式、鏈接、捐贈二維碼等，就不逐一介紹了。

總結(jié)

GitBook 制作電子書非常實用，雖然不算難，但也需要一定的學習成本。

本文介紹的功能完美符合我自己的使用需求，都是我自己的經(jīng)驗總結(jié)。文中介紹了很多可能會遇到的問題和解決方法，看起來好像使用 GitBook 會有很多坑，但其實這些問題只需要解決一次就可以。電子書創(chuàng)建成功后，可以永久使用，且可以發(fā)送給任何人使用，花些時間解決問題也是值得的。

為了能更好地體驗GitBook的效果，我將本文的內(nèi)容做成了靜態(tài)網(wǎng)頁電子書，可以獲取體驗。
百度網(wǎng)盤：https://pan.baidu.com/s/1BoK8Qf1q60omlIHJDEqh8Q?pwd=ty6m

??歡迎 點贊?? 收藏? 評論?? 關(guān)注? 如有錯誤敬請指正！

? 學Python，點擊下方名片關(guān)注我。?文章來源地址http://www.zghlxwxcb.cn/news/detail-765864.html

到了這里，關(guān)于用GitBook制作自己的網(wǎng)頁版電子書的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！