This article taken from "The Great Markdown" , Author: BI little trouble

Great Markdown

GitBook is a command-line tool developed based on Node.js, which can be used to easily manage e-books. GitBook is currently the most popular open source book writing solution.

Using GitBook allows creators to focus on writing and freely sway, without having to worry too much about content layout, publishing and version management.

In addition to managing e-books through the GitBook command line, you can also write and manage e-books online ( gitbook.com ) or using the desktop editor Gitbook Editor.

For newbies, I recommend using the Gitbook Editor to write and manage e-books, because it integrates the functions of the GitBook command, Markdown editor, and Git, and the content can be synchronized with gitbook.com/Gitlab/GitHub through Git for easy version management and team cooperation.

For programmers or people familiar with Git and Markdown, I recommend using the GitBook command line + Typora + SourceTree to write and manage e-books. Using professional tools to do professional things is much more efficient than Gitbook Editor.

GitBook is open source, address: https://github.com/GitbookIO/gitbook

Features of GitBook:

Supports Markdown or AsciiDoc syntax
Can export static sites or e-books (PDF, epub, mobi)
Support multiple languages
Can set cover
Support variables, templates and template inheritance
There are rich plugins

GitBook's tool portfolio:

Node.js: In order to install GitBook using npm, you must first install Node.js.
GitBook command: a command-line tool developed based on Node.js, used to create and manage e-books.
Markdown: GitBook uses Markdown for writing, and the author no longer has to worry about typesetting.
Git: GitBook uses Git to manage writing content, facilitating multi-person collaboration and version management.
Github / Gitlab: Like the code, the written content can be hosted on Github or Gitlab.
gitbook.com : A website for writing, publishing, and hosting e-books online.

GitBook usage scenarios:

Build a company's internal document platform for data sharing within the company.
Publish open source e-books for sharing your knowledge on the Internet to benefit the public.

GitBook environment configuration

Before we start, we need to install:

nodejs
gitbook

Install Node.js

Because GitBook is developed using Node.js, you need to install it through the Node.js package management tool NPM, so you must install Nodejs before you start.

Node.js download address: https://nodejs.org/zh-cn/

NPM (node package manager), usually called node package manager. Use NPM to install, uninstall, update, view, search, and publish node packages.

After installing Node.js, NPM can be used directly.

Install GitBook

Command line tool for installing GitBook using NPM:

$ sudo npm install gitbook-cli -g

After the installation is complete, check the version of GitBook:

$ gitbook --version
CLI version: 2.3.0
GitBook version: 3.2.2

Update GitBook command:

$ npm update gitbook-cli -g

Uninstall GitBook command:

$ sudo npm uninstall gitbook-cli -g

note:

In this example, the command to install GitBook globally is used, and there is another way to install locally. What is the difference between the two ways?

Local installation: The installation package will be downloaded to the current directory, so it can only be used in the current directory.
Global installation: The installation package will be downloaded to a specific system directory, the installation package can be used in all directories.

For example, check where is the global installation under macOS installed?

$ which gitbook
/usr/local/bin/gitbook

GitBook is installed in the / usr / local / bin / directory, so it can be used globally.

This article taken from "Markdown Practical Guide" Author: Bi little trouble

Quick start GitBook

Initialize GitBook

# 创建 mygitbook 文件夹，并切换到这个文件夹下面
~$ mkdir mygitbook && cd mygitbook

# 初始化 gitbook 工作目录，创建必要的文件
~$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

Then it will initialize the GitBook directory and create two md format files README.md and SUMMARY.md

README.md -The project description is written in this file.
SUMMARY.md -GitBook's directory structure is configured here.

Define the directory structure

Two methods

There are two ways to define the directory structure in the Summary.md file.

Method ➊. First define the directory structure, and automatically generate the folder and Markdown file corresponding to the directory structure through gitbook init.

Method ➋. First create a folder and Markdown file and then edit the directory structure.

SUMMARY.md

What does the directory structure of SUMMARY.md look like? look down:

# Summary

* [项目简介](README.md)
* [快速开始](docs/快速开始.md)
 * [环境搭建](docs/环境搭建.md)
 * [简单使用](docs/简单使用.md)
* [学入学习](docs/深入学习)

After this directory is created, execute the command in the root directory:

~$ gitbook init

Those directories and files that are not available will be created:

info: create docs/快速开始.md
info: create docs/环境搭建.md
info: create docs/简单使用.md
info: create docs/深入学习.md
info: create SUMMARY.md
info: initialization is finished

Note: gitbook init only supports generating two levels of directories

Start service

Execute the command in the root directory:

~$ gitbook serve

result:

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

info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 5 pages
info: found 0 asset files
info: >> generation finished with success in 1.9s !

Starting server ...
Serving book on http://localhost:4000 # 注意浏览地址

Execute gitbook servethe command, you will first compile books gitbook build, if there is no problem to open a Web server, the default port 4000 to listen. If there is a problem with compilation, an error message will be thrown.