GitBook tutorial

background

Because the scattered knowledge was written in Gist On, the search is not very systematic, so I plan to move to GitBook Unified management, and GitBook After writing and compiling, you can generate a static page and publish it to the blog, which looks full.

Introduction to GitBook

GitBook preparation

Install node js

GitBook is a node based JS command line tool, download and install Node.js , after the installation is completed, you can use the following command to verify whether the installation is successful.

 

$ node -v
v7.7.1

Installing GitBook

Enter the following command to install GitBook.

 

$ npm install gitbook-cli -g

After the installation is completed, you can use the following command to verify whether the installation is successful.

 

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

For more details, please refer to GitBook installation documentation To install GitBook.

editor

You can use VsCode, Typora and other favorite to edit.

be all eagerness to see it

After GitBook is ready, we enter a directory where you want to write books and enter the following command.

 

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

You can see that he will create readme MD and summary MD these two files, readme MD should be no stranger, that is, documentation, and summary MD is actually the chapter directory of the book. Its default content is as follows:

 

# Summary

* [Introduction](README.md)

Next, we enter the $gitbook serve command, and then enter it in the browser address bar http://localhost:4000 You can preview the book.

The effect is as follows:

After running this command, a file will be generated in the folder of the book_ The contents in the book folder are the generated html files. We can use the following command to generate web pages without opening the server.

 

gitbook build

Let's introduce the directory structure and related files of GitBook in detail.

directory structure

The basic directory structure of GitBook is as follows:

 

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

Let's talk about book JSON and summary MD file.

book.json

This file is mainly used to store configuration information. I will release my configuration file first.

 

{
    "title": "Blankj's Glory",
    "author": "Blankj",
    "description": "select * from learn",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "styles": {
        "website": "./styles/website.css"
    },
    "structure": {
        "readme": "README.md"
    },
    "links": {
        "sidebar": {
            "My Kennel": "https://blankj.com"
        }
    },
    "plugins": [
        "-sharing",
        "splitter",
        "expandable-chapters-small",
        "anchors",

        "github",
        "github-buttons",
        "donate",
        "sharing-plus",
        "anchor-navigation-ex",
        "favicon"
    ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/Blankj"
        },
        "github-buttons": {
            "buttons": [{
                "user": "Blankj",
                "repo": "glory",
                "type": "star",
                "size": "small",
                "count": true
                }
            ]
        },
        "donate": {
            "alipay": "./source/images/donate.png",
            "title": "",
            "button": "appreciate",
            "alipayText": " "
        },
        "sharing": {
            "douban": false,
            "facebook": false,
            "google": false,
            "hatenaBookmark": false,
            "instapaper": false,
            "line": false,
            "linkedin": false,
            "messenger": false,
            "pocket": false,
            "qq": false,
            "qzone": false,
            "stumbleupon": false,
            "twitter": false,
            "viber": false,
            "vk": false,
            "weibo": false,
            "whatsapp": false,
            "all": [
                "google", "facebook", "weibo", "twitter",
                "qq", "qzone", "linkedin", "pocket"
            ]
        },
        "anchor-navigation-ex": {
            "showLevel": false
        },
        "favicon":{
            "shortcut": "./source/images/favicon.jpg",
            "bookmark": "./source/images/favicon.jpg",
            "appleTouch": "./source/images/apple-touch-icon.jpg",
            "appleTouchMore": {
                "120x120": "./source/images/apple-touch-icon.jpg",
                "180x180": "./source/images/apple-touch-icon.jpg"
            }
        }
    }
}

I believe many nodes can guess what it means. I'd better briefly introduce it.

title

Title of this book

author

Author of this book

description

Description of this book

language

The language of this book can be set as "zh Hans" in Chinese

gitbook

Specifies the GitBook version to use

styles

Custom page styles

structure

Specify the file names corresponding to Readme, Summary, Glossary, and Languages

links

Add link information in the left navigation bar

plugins

Configure the plug-ins used

pluginsConfig

Configure the properties of the plug-in

SUMMARY.md

This file mainly determines the chapter directory of GitBook. It represents the parent-child relationship of the file through the list syntax in Markdown. The following is a simple example:

 

# Summary

* [Introduction](README.md)
* [Part I](part1/README.md)
    * [Writing is nice](part1/writing.md)
    * [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
    * [We love feedback](part2/feedback_please.md)
    * [Better tools for authors](part2/better_tools.md)

The directory structure corresponding to this configuration is as follows:

We divide the GitBook into several different parts by using the title or horizontal split line, as shown below:

 

# Summary

### Part I

* [Introduction](README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)

### Part II

* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)

---

* [Last part without title](part3/title.md)

The directory structure corresponding to this configuration is as follows:

plug-in unit

GitBook has Plug in official website , there are five plug-ins by default, including highlight, search, sharing, font settings and livereload. If you want to remove the built-in plug-ins, you can add - in front of the plug-in name, for example:

 

"plugins": [
    "-search"
]

If you want to configure the plug-in you can use in book JSON file can be added, for example, we add plugin-github , we are in book JSON can be configured as follows:

 

{
    "plugins": [ "github" ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/your/repo"
        }
    }
}

Then input gitbook install in the terminal/ Just.

If you want to specify the version of the plug-in, you can use plugin@0.3.1 , because some plug-ins may not be upgraded with the upgrade of GitBook version.

epilogue

This is my summary of the use of GitBook. I hope it can help small partners who need it in the future.


Link: https://www.jianshu.com/p/421cc442f06c

Posted by scarlson on Sun, 08 May 2022 10:13:25 +0300