Article directory
1. Install Nodejs
To use Gitbook locally on a Windows 10 system, you need to install the gitlab-cli tool. The gitbook-cli tool is based on Nodejs, so you need to install Nodejs first.
If you are a beginner, you can refer toNodejs----Installing Nodejs based on Windows 10 system Install Nodejs, you need to pay attention here, this article verifies It is possible to install the 16.20.1 version of Nodejs, so it is recommended to also install the 16.20.1 version. Do not install a higher version. If you have multiple front-end projects at hand, then this article is still a direct reference.< a i=3>nvm----Install and manage multiple Nodejs versions simultaneously on the Windows 10 system and enable flexible and convenient switching tools By installing nvm, you can install multiple Nodejs on the Windows system version, so that the Nodejs version can be flexibly switched in subsequent project development. This article demonstrates using the nvm tool
2. Install Gitbook
(1) First check the version of Nodejs installed locally through nvm, as shown below. Three versions have been installed here.
(2) Therefore, you can switch the Nodejs version through the nvm use 16.20.1 command. After the switch is completed, check again and confirm as follows that the Nodejs version has been switched to the 16.20.1 version.
(3) Then you can start installing the gitbook-cli package and execute the following command
npm install gitbook-cli -g
(4) Then execute the following command to check the version number of gitbook-cli and install gitbook
gitbook -V
(5) The following errors may occur at this time. If they do not occur, skip this step directly. If the following errors occur, you need to solve them.
According to the error message here, open the D:\ProgrameFile\nvm\v16.20.1\global\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js file and find 287 lines of code, as you can see This problem will be triggered if the statFix function is called.
Search this file for the location where the staFix function is called, as shown below. Only the following three lines are calling
I also checked some information on the Internet and found that many people have encountered this problem, and the feedback only needs to comment out these three lines of code, so here we also comment out these three lines of code, as shown in the figure below.
Then save, and then execute the gitbook -V command, as shown in the figure below, you can see that the installation has been successful.
3. How to use gitbook
(1) Here we take the https://github.com/redrose2100/docs code repository as an example. After downloading this docs project locally, for example, if you want to write an e-book about Linux, create a new one in the docs project here. A folder linux for storing e-books to be written. The directory structure is as follows:
(2) Enter the linux folder in the cmd window, and then execute the gitbook init command. Here again, the error shown below is encountered.
At this time, you need to find the file C:\Users\Administrator.gitbook\versions\3.2.3\lib\init.js, then comment out line 72, and then modify it to line 73 of code< a i=1> About to
return fs.writeFile(filePath, summary.toText(extension));
change into:
return summary.toText(extension).then(stx=>{
return fs.writeFile(filePath, stx);});
After saving, re-execute the gitbook init command. At this time, you can see that the execution is successful.
(3) At this time, two new files README.md and SUMMARY.md will be generated. The directory structure is as shown below:
(4) Do not make any modifications at this time, and then directly execute the gitbook serve command to start the service, as shown in the following figure:
(5) Follow the prompts and open http://localhost:4000/ in the browser to open the e-book page, as shown in the figure below:
4. Design the directory structure of e-books
First, we need to plan the directory structure of the e-book. For example, if we want to write an e-book about Linux, then we can roughly design the following directory:
第一章 Linux 概述
1.1 Linux 简介
1.2 Linux 特点
1.3 Linux 的发展历史
第二章 Linux 常用命令
2.1 用户与权限管理命令
2.2 文件管理命令
2.3 磁盘管理命令
第三章 shell 编程
3.1 条件语句
3.2 循环语句
3.3 shell 编程实例
(1) First create three folders under the linux file, such as ch01, ch02, and ch03, to store the content of the three chapters, and then continue to create md files in each created subfolder, such as ch01/1_1.md, ch01/1_2.md, ch01/1_3.md, ch02/2_1.md, ch02/2_2.md, ch02/2_3.md, ch03/3_1.md, ch03/3_2.md, ch03/3_3.md, at this time The file directory structure is as shown below:
(2) The linux/README.md document can be understood as the preface of the e-book, while SUMMARY.md is a directory file. Here, for example, first modify the content of the README.md document to the following content:
# 前言
这是一本关于 Linux 的技术实战类型的书籍
(3) Then the key point is to write the SUMMARY.md document, that is, write the table of contents. Here, according to the electronic book planning table of contents, the contents of the SUMMARY.md file can be written as follows:
# 目录
* [前言](README.md)
* [第一章 Linux 概述]()
* [1.1 Linux 简介](ch01/1_1.md)
* [1.2 Linux 特点](ch01/1_2.md)
* [1.3 Linux 的发展历史](ch01/1_3.md)
* [第二章 Linux 常用命令]()
* [2.1 用户与权限管理命令](ch02/2_1.md)
* [2.2 文件管理命令](ch02/2_2.md)
* [2.3 磁盘管理命令](ch02/2_3.md)
* [第三章 Linux shell 编程]()
* [3.1 条件语句](ch03/3_1.md)
* [3.2 循环语句](ch03/3_2.md)
* [3.3 shell 编程实例](ch03/3_3.md)
(4) Stop the gitbook serve command, then re-execute the gitbook serve command, and then open http://localhost:4000/ according to the prompts. The result is as shown in the figure below. It can be seen that at this time, the e-book is the same as the one we imagined in our mind. The format is almost there.
5. Set up common configurations of gitbook
(1) Create the book.json file in the linux folder, which is the same directory as SUMMARY.md. The file content is as follows:
{
"title": "Linux 从入门到精通",
"author": "redrose2100",
"description": "Linux 从入门到精通",
"language": "zh-hans",
"gitbook": "3.2.3",
"links": {
"sidebar": {
"GitHub": "https://github.com/redrose2100/docs"
}
}
}
in:
- title: book title
- author: author
- description: brief description
- language: Language, use zh-hans here to switch the page to Chinese
- gitbook: The version number of gitbook, which can be seen during installation
- links.sidebar: You can set the connection, such as setting the github link to transfer to the docs code warehouse address
(2) Execute the gitbook serve command again, and then reopen http://localhost:4000/, as shown in the figure below. At this time, all the original English words on the page have been switched to Chinese, and a Github has been added on the left After clicking the link, you can jump to the docs code warehouse on github.
At this point, gitbook has been successfully run on Windows. Of course, in order to be able to write more colorful e-books, there are many subsequent functions such as commonly used plug-ins, such as blocking unnecessary information, etc., which need to be further optimized. , subsequent optimization will be continued in detail in other articles, and will not be expanded upon here for the time being.