Create and publish personal e-books using Gitbook

Requirements description

Gitbook can make and release personal e-books for everyone, and can maximize the use of "group intelligence" to improve reading quality and enjoy the creative process.

gitbook COM is a simple personal online book website, where you can organize your own documents into a book for easy reading. gitbook provides two solutions,

1. you can directly apply for account creation on the gitbook official website.

2. build one by themselves through the command line development tool provided by them.

Let's introduce the second scheme. The gitbook command-line tool first needs node JS, https://nodejs.org/zh-cn/download/

system description

System: Centos7
​
IP:  192.168.1.5(Or ECS)
​
Address: https://g.xgss.net/
​
Github Page Address: gitbook.xgss.net
​
github warehouse:https://github.com/funet8/book.git
​
copy

1, Installing nodejs

Install nodejs and npm using yum

The nodejs version should not be too high for Android. The author installed nodejs v8 version, otherwise an error will be reported: the installed v14.17.6 has an error:

      if (cb) cb.apply(this, arguments)
TypeError: cb.apply is not a function
    at /usr/local/node-v14.17.6/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
    at FSReqCallback.oncomplete (fs.js:193:5)
copy

1 update node JS various versions yum source

Node.js v8.x Installation command
curl --silent --location https://rpm.nodesource.com/setup_8.x | bash -
​
Node.js v7.x Installation command
curl --silent --location https://rpm.nodesource.com/setup_7.x | bash -
​
Node.js v6.x Installation command
curl --silent --location https://rpm.nodesource.com/setup_6.x | bash -
​
Node.js v5.x Installation command
yum install node.js
# yum install -y nodejs
​
# node -v
v8.17.0
copy

Install cnpm (bosses who have confidence in their own network can ignore it)

Because it is relatively slow in China, we can install cnpm of Taobao additionally, and use cnpm when it is slow

# npm install -g cnpm --registry=https://registry.npm.taobao.org
copy

2, Installing the gitbook cli tool

GitBook cli is a utility that installs and uses multiple versions of GitBook on the same system. And automatically install the required version of GitBook to generate a book. Execute the `npm install GitBook cli -g terminal command to install.

# npm install gitbook-cli -g
copy

You can verify through gitbook --version. If you are prompted that there is no such command, you need to enter an absolute path or create a soft link

# gitbook --version
CLI version: 2.3.2
Installing GitBook 3.2.3
copy

Note: the first time the terminal runs the gitbook command, it may automatically install the gitbook, because the CLI was just installed, and then the CLI will automatically install the gitbook.

If you want to uninstall the CLI, use NPM uninstall gitbook cli -g to remove it.

Of course, GitBook is far more powerful than we thought. We can also view it through gitbook help:

# gitbook help
copy

Initialize a Book

The command to initialize a book is gitbook init,

First, create a project directory at the terminal and enter this directory:

~ mkdir git_book
~ cd git_book
~ gitbook init
gitbook init Will be created in an empty project README.md and SUMMARY.md Two files:
README.md File is the introduction file of the project.
SUMMARY.md yes gitbook A catalog of books.
copy

If summary The MD file contains the following contents:

vim SUMMARY.md
* [Project introduction](README.md)
* http
    * [http explain](doc/http/http analysis.md)
        * [tcp explain](doc/http/tcp/tcp explain.md)
            * [udp explain](doc/http/tcp/udp/udp explain.md)
* HTML
    * [HTML5-Characteristic description](doc/html/HTML5-Characteristic description.md)
copy

Local startup service writing book

The terminal opens the project directory and starts the service using gitbook serve:

gitbook serve
copy

Then open it in the browser according to the prompt of the terminal http://localhost:4000 View books

https://app.gitbook.com/@star-2/s/linux/v/gitbook.xgss.net/

6. initialize a Book

git clone git@github.com:funet8/book.git
cd book
gitbook init

warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished

gitbook init Will be created in an empty project README.md and SUMMARY.md Two files:
README.md File is the introduction file of the project.
SUMMARY.md yes gitbook A catalog of books.
copy

If summary The MD file contains the following contents:

# vim SUMMARY.md
* [Project introduction](README.md)
* http
    * [http explain](doc/http/http analysis.md)
        * [tcp explain](doc/http/tcp/tcp explain.md)
            * [udp explain](doc/http/tcp/udp/udp explain.md)
* HTML
    * [HTML5-Characteristic description](doc/html/HTML5-Characteristic description.md)
copy

Local startup service writing book

The terminal opens the project directory and starts the service using gitbook serve:

# gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 

Error: Couldn't locate plugins "search-pro, back-to-top-button", Run 'gitbook install' to install plugins from registry.
# gitbook install
# gitbook serve
Starting server ...
Serving book on http://localhost:4000

Open port:
iptables -A INPUT -p tcp --dport 4000 -j ACCEPT
service iptables save
systemctl restart iptables.service
systemctl enable iptables.service

Note: gitbook serve Command generates a_book Folder for,This folder is the final generated project.
copy

Enter in the browser: http://192.168.1.5:4000 open

7. document packaging

You can use the gitbook build command to build the final project:

# gitbook build
info: 9 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "search-pro"... OK 
info: loading plugin "back-to-top-button"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 2 pages 
info: found 2 asset files 
info: >> generation finished with success in 0.4s ! 
copy

After the command is executed, the folder of book will be generated under the project, which is the final generated project. There is an index in the book folder HTML file, which is the HTM entry of the document website_ Copy the book folder to the server, and then lead the web service entry to index HTML to complete the deployment of the document website.

If you want to view the detailed records of the output directory, you can use gitbook build. /-- Log=debug --debug to build the view.

8. generate an e-book (no operation for the time being when an error is reported)

GitBook can generate a website, but it can also output content as e-books (ePub, Mobi, PDF).

# Generate a PDF file
$ gitbook pdf ./ ./mybook.pdf
 Prompt error:  InstallRequiredError: "ebook-convert" is not installed.


# Generate an ePub file
$ gitbook epub ./ ./mybook.epub

# Generate a Mobi file
$ gitbook mobi ./ ./mybook.mobi
copy

9. deploy the project to GitHub Pages

This part needs to use git and github websites. If you can't, please search the documents on the Internet by yourself.

Since the project generated by gitbook and the source code of the document are two parts, you can put the document on the master branch and the deployed website on the GH pages branch.

10. create a warehouse on github

This warehouse is used to store the projects you write and deploy. Please find out how to create them by yourself.

The author uses https://github.com/funet8/book.git

11. submit local projects to github warehouse

Create one in the project gitignore file, as follows:

vim .gitignore
# Ignore gitbook generated project directories
_book
copy

Then the terminal opens the project and inputs the following command to submit the document project to the github:

~ git commit -m 'initialization gitbook Local project'
~ git remote add origin git@github.com:funet8/book.git
~ git push -u origin master
copy

After the above command is executed, the code will be submitted to the repository on github. Note that the warehouse address should be replaced with your own link.

12. generate the project and upload it to the GH pages branch of the github warehouse

Because there are too many packaged commands, for simplicity, write a script command to execute automatically. Of course, you can also execute these commands by the terminal itself.

To facilitate deployment, you can create a script file gitbook_ Xgss_ COM_ GH_ Pages SH, the function will_ The book directory is pushed to the GH pages branch in the git repository

The contents are as follows:

vim gitbook_xgss_com_gh_pages.sh
#!/usr/bin/env sh
## Will_ The book directory is pushed to the GH pages branch in the git repository

# Define warehouse address
Git_Url='git@github.com:funet8/book.git'

echo 'Start command execution'
# Generate static file
echo 'Execute command: gitbook build .'
gitbook build .

# Enter generated folder
echo "Execute command: cd ./_book\n"
cd ./_book

# Initializing a warehouse is just an initialization operation, and the files in the project have not been tracked
echo "Execute command: git init\n"
git init

# Save all changes
echo "Execute command: git add -A"
git add -A

# Submit revised documents
echo "Execute command: commit -m 'deploy'"
git commit -m 'deploy.sh'

# If you publish to https://<username> Github Io/<repo>
echo "Execute command: git push -f $Git_Url master:gh-pages"
git push -f $Git_Url master:gh-pages

# Return to the previous working directory
echo "Go back to the working directory"
cd -
copy

After successful execution, open your github repository and select the branch branch. You will find an additional GH pages branch. After opening this branch, there will be an index HTML file. This indicates that the deployed code has been uploaded successfully. Note: if there is no GH pages branch, it means that the deployment is not successful. Please check the terminal just executed to see where the error is reported, and solve the error until the deployment is successful.

Write shell script gitbook_ Xgss_ COM_ Main SH, the function will be pushed to the main branch in git warehouse, and then merged into gitbook Xgss Net branch

vim gitbook_xgss_com_main.sh
#!/bin/bash
## The function will be pushed to the main branch in the git warehouse, and then merged into the gitbook Xgss Net branch

NowTime=`date +%Y%m%d-%H:%M:%S` 

echo 'Switch to primary branch'
git checkout main
echo 'Submit all files in the current directory'
git add .

echo 'Add comment to current branch'
git commit -m "Script submitted automatically on: $NowTime"

echo 'Submit to remote warehouse'
git push

# Merge a branch to the current branch
git checkout gitbook.xgss.net
git merge main
git push
echo 'Switch back to the main branch'
git checkout main
copy

13. configure GitHub Pages to display websites

14. Explanation of gitbook configuration file

If you want to personalize your website in more detail or use plug-ins, you need to use a configuration file. After the configuration file is written, you need to restart the service or repackage to apply the configuration. The configuration file name of gitbook is book JSON, first create a book JSON file. Book JSON main content:

{
    "title": "One of my books",
    "author" : "yu",
    "description" : "The description of my first book is very good",
    "language" : "zh-hans",
    "structure": {
        "readme": "introduction.md"
    },
    "plugins": [
        "-lunr",
        "-search",
        "search-pro",
        "back-to-top-button"
    ],
    "pluginsConfig": {
        "anchor-navigation-ex": {
            "isShowTocTitleIcon": true
        }
    },
    "links" : {
        "sidebar" : {
            "Personalized link 1" : "https://www.baidu.com",
            "Personalized link 2" : "https://www.baidu.com"
        }
    },
    "styles": {
        "website": "styles/website.css",
        "ebook": "styles/ebook.css",
        "pdf": "styles/pdf.css",
        "mobi": "styles/mobi.css",
        "epub": "styles/epub.css"
    }
}
copy

Book Some main parameters in JSON

  • title Title
  • Author author
  • Description Description, corresponding to the description of the gitbook website
  • The language used in language, Zh Hans, is simplified Chinese and corresponds to <html lang= "zh Hans" >
  • structure specifies the file names corresponding to Readme, Summary, Glossary and Languages. The following are the corresponding variables and default values of these files: Variabledescriptionstructure Readmereadme file name (defaults to readme.md) structure Summarysummary file name (defaults to summary.md) structure Glossaryglossary file name (defaults to glossary.md) structure Languageslanguages file name (defaults to Lang s.md) for example, if you want to give the readme file a name, you can use the following configuration
"structure": {
    "readme": "introduction.md"
},
copy

After using this configuration, the gitbook service will not find the readme file, but the introduction file as the project description. In this way, the readme file can be completely regarded as the code warehouse description document.

  • A list of plug-ins used by plugins. All plug-ins are written here, and then installed using gitbook install.
  • pluginsConfig plug-in configuration information. If the plug-in requires configuration parameters, fill in here.
"links" : {
    "sidebar" : {
        "Personalized link 1" : "https://www.baidu.com"
    }
}
copy
  • Styles customize page styles. Various formats correspond to their respective css files "styles": { "website": "styles/website.css", "ebook": "styles/ebook.css", "pdf": "styles/pdf.css", "mobi": "styles/mobi.css", "epub": "styles/epub.css" }

Configure default theme

The default theme can be configured for the following effects. For example, if the sidebar menu displays the title number, you can write the following fields in the pluginsConfig parameter of the configuration file:

{
    "pluginsConfig": {
        "theme-default": {
            "showLevel": true
        }
    }
}
copy

Tags: git Web Development Cloud Server gitbook

Posted by GreyBoy on Mon, 30 May 2022 19:31:52 +0530