Gitbook introductory tutorial using gitbook-cli to develop e-books

Time:2019-9-11

gitbookThere are three main ways to generate e-books:

  • gitbook-cliCommand line operation, concise and efficient, suitable for people engaged in software development.
  • gitbook-editorEditor operation, visual editing, suitable for literary creators without programming experience.
  • gitbook.comOfficial website operation, online editing and real-time publishing, suitable for users who have no local environment and access to the Internet scientifically.

This article mainly explains the first one.gitbook-cliCommand-line operations, the other two see the other two tutorials.

gitbookSome Common Commands

installgitbook-cliScaffolding tools

The machine has been installed.node.jsDevelopment environment, run after installationgitbook -VThe ability to print publication information indicates successful installation.

$ sudo npm install -g gitbook-cli

Refer to Environmental Requirements for Installation and Configuration

Initializationgitbookproject

Initialize the project according togitbookSpecifications are automatically createdREADME.mdandSUMMARY.mdTwo documents for specific purposes are listed below.

actuallySUMMARY.mdIt’s a catalogue of chapters and programs of e-books.gitbookThe corresponding file directory structure is initialized, so it is mainly used forInitial phase of development.

$ gitbook init

start-upgitbookproject

Start the local service, the program can preview the effect of E-book in browser without error: http://localhost:4000

Because it can preview the effect of E-book in real time, and most development environments are built in local rather than remote servers, it is mainly used forDevelopment and debugging phase.

$ gitbook serve

structuregitbookStatic web page

Construct static web pages without starting local servers. By default, generated files are stored in_book/Directories, of course, output directories are configurable, not yet covered, see the Advanced Section.

Output of static web pages can be packaged and uploaded to the server or uploaded to the server.githubAnd other websites for hosting, so mainly used forRelease preparation phase.

$ gitbook build

Summary of chapters

  • gitbook initInitializationREADME.mdandSUMMARY.mdTwo files.
  • gitbook buildBuild locally but do not run the service, default output to_book/Catalog.
  • gitbook serveBuild and run the service locally, accessed by defaulthttp://localhost:4000Real-time preview.
# Create a `gitbook'demo project
$ mkdir gitbook-demo

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

# Start the local server
$ gitbook serve
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 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 1.2s ! 

Starting server ...
Serving book on http://localhost:4000

# View the current directory structure
$ tree
.
├── README.md
├── SUMMARY.md
└── _book
    ├── gitbook
    │   ├── fonts
    │   │   └── fontawesome
    │   │       ├── FontAwesome.otf
    │   │       ├── fontawesome-webfont.eot
    │   │       ├── fontawesome-webfont.svg
    │   │       ├── fontawesome-webfont.ttf
    │   │       ├── fontawesome-webfont.woff
    │   │       └── fontawesome-webfont.woff2
    │   ├── gitbook-plugin-fontsettings
    │   │   ├── fontsettings.js
    │   │   └── website.css
    │   ├── gitbook-plugin-highlight
    │   │   ├── ebook.css
    │   │   └── website.css
    │   ├── gitbook-plugin-livereload
    │   │   └── plugin.js
    │   ├── gitbook-plugin-lunr
    │   │   ├── lunr.min.js
    │   │   └── search-lunr.js
    │   ├── gitbook-plugin-search
    │   │   ├── lunr.min.js
    │   │   ├── search-engine.js
    │   │   ├── search.css
    │   │   └── search.js
    │   ├── gitbook-plugin-sharing
    │   │   └── buttons.js
    │   ├── gitbook.js
    │   ├── images
    │   │   ├── apple-touch-icon-precomposed-152.png
    │   │   └── favicon.ico
    │   ├── style.css
    │   └── theme.js
    ├── index.html
    └── search_index.json

11 directories, 27 files
$

gitbookDirectory structure description

Since an e-book is to be written, a minimum chapter introduction and chapter details are naturally indispensable.

Of course, the title, author and contact information need to be specified, if not specified, once the default cooperation is adopted, 80% of them do not meet our expectations, maybe they will become anonymous e-books? So configuration files generally need to be set manually!

After all, not every e-book has a vocabulary to explain. If the vocabulary involved is explained in detail, then naturally no vocabulary document is needed.

Simply explain the role of each document:

  • README.mdIs the default home page file, equivalent to the home page of the websiteindex.htmlIt usually introduces text or related navigation links.
  • SUMMARY.mdIs the default summary file, mainly based on the content of the file to generate the corresponding directory structure.README.mdThe same is true.gitbook initInitialize the important files created by default.
  • _bookIs the default output directory that holds the originalmarkdownAfter renderinghtmlFiles that can be packaged directly to serversStatic web siteUsage. Usually executiongitbook buildorgitbook serve Automatic generation.
  • book.jsonIs a configuration file for personalizationgitbookRelevant configurations, such as defining e-book titles, covers, authors, etc., are generally optional, although manually created.
  • GLOSSARY.mdIt is the default vocabulary, mainly explaining the detailed explanation of professional vocabulary, so that when reading professional vocabulary, there will be corresponding prompt information. It is also manually created but optional.
  • LANGS.mdIs the default language file for international version translation, andGLOSSARY.mdThe same is created manually but optionally.

README.mdHome Page Document [Must]

editREADME.mdDocuments, Write Points and Start Local Services(gitbook serve) Real-time preview effect.

SUMMARY.mdSummary document [must]

First stop the local service, edit the chapter and catalog structure, and then re-initialize it.(gitbook init) Create the corresponding directory automatically.

_bookOutput directory [optional]

implementgitbook buildorgitbook serveStatic Web pages are automatically generated after commands.

# Building e-books
$ gitbook build
info: 7 plugins are installed 
info: 6 explicitly listed 
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 0.7s ! 

# View the output directory
$ tree _book/
_book/
├── first
│   ├── 01.html
│   └── 02.html
├── first.html
├── gitbook
│   ├── fonts
│   │   └── fontawesome
│   │       ├── FontAwesome.otf
│   │       ├── fontawesome-webfont.eot
│   │       ├── fontawesome-webfont.svg
│   │       ├── fontawesome-webfont.ttf
│   │       ├── fontawesome-webfont.woff
│   │       └── fontawesome-webfont.woff2
│   ├── gitbook-plugin-fontsettings
│   │   ├── fontsettings.js
│   │   └── website.css
│   ├── gitbook-plugin-highlight
│   │   ├── ebook.css
│   │   └── website.css
│   ├── gitbook-plugin-lunr
│   │   ├── lunr.min.js
│   │   └── search-lunr.js
│   ├── gitbook-plugin-search
│   │   ├── lunr.min.js
│   │   ├── search-engine.js
│   │   ├── search.css
│   │   └── search.js
│   ├── gitbook-plugin-sharing
│   │   └── buttons.js
│   ├── gitbook.js
│   ├── images
│   │   ├── apple-touch-icon-precomposed-152.png
│   │   └── favicon.ico
│   ├── style.css
│   └── theme.js
├── index.html
├── search_index.json
└── second.html

10 directories, 28 files
$

book.jsonConfiguration file [optional]

New in the root directorybook.jsonConfiguration files, complete support items refer to the official documents, below is only a list of commonly used configuration items.

titleTitle

Titles of Books

Example:

"Title": "Snow Dream Technology Station"

authorauthor

Author of Books

Example:

"author": "snowdreams1006"

descriptiondescribe

A Brief Description of Books

Example:

"Description": "Snow Dream Technology Station, also known as snowdreams 1006 technology cabin. It mainly shares personal learning experience, a word, for reference only."

isbnInternational Standard Book Number

International Standard Book Number of Books

Example:

  "isbn": "978-0-13-601970-1"

Please refer to ISBN Search.

languagelanguage

Support Language Items: Default English(enSet to Simplified Chinese(zh-hans)

en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw

Example:

"language": "zh-hans"

directionReading order

Reading order, from right to left(rtl) Or from left to right(ltrThe default value depends on the language value.

Example:

"direction" : "ltr"

gitbookEdition

AppointgitbookVersion, supports SemVer specification, accepts similar>=3.2.3Conditions.

Example:

"gitbook": "3.2.3"

rootroot directory

Designated storagegitbookDocuments (exceptbook.jsonThe root directory of the file itself

Example:

"root": "."

linksSide Bar Links

Add links to the left navigation bar to support external links

Example;

"links": {
    "sidebar": {
        "My website": "https://snowdreams 1006.cn/"
    }
}

stylescustom style

Customize global style

Example:

"styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
}

pluginsPlug-in unit

Configure additional list of plug-ins to run after adding new plug-insgitbook installInstall to the current project.

gitbookBy default, there are five plug-ins, which are:

  • highlightGrammar highlighting plug-in
  • searchSearch plug-in
  • sharingShare plug-ins
  • font-settingsFont Settings Plug-in
  • livereloadHot Loading Plug-in

Some common plug-ins will be introduced later. For more plug-ins, please visit the official plug-in market.

Example:

"plugins": [
    "github",
    "pageview-count",
    "mermaid-gb3",
    "-lunr", 
    "-search", 
    "search-plus",
    "splitter",
    "-sharing", 
    "sharing-plus",
    "expandable-chapters-small",
    "anchor-navigation-ex",
    "edit-link",
    "copy-code-button",
    "chart",
    "favicon-plus",
    "donate"
]

pluginsConfigPlug-in configuration

Install the corresponding configuration items of the plug-in, which specific configuration items are provided by the plug-in itself, should visit the plug-in official website for query.

"pluginsConfig": {
    "github": {
      "url": "https://github.com/snowdreams1006/snowdreams1006.github.io"
    },
    "sharing": {
       "douban": true,
       "facebook": false,
       "google": false,
       "hatenaBookmark": false,
       "instapaper": false,
       "line": false,
       "linkedin": false,
       "messenger": false,
       "pocket": false,
       "qq": true,
       "qzone": true,
       "stumbleupon": false,
       "twitter": false,
       "viber": false,
       "vk": false,
       "weibo": true,
       "whatsapp": false,
       "all": [
           "facebook", "google", "twitter",
           "weibo", "instapaper", "linkedin",
           "pocket", "stumbleupon"
       ]
   },
   "edit-link": {
      "base": "https://github.com/snowdreams1006/snowdreams1006.github.io/blob/master",
      "Label": "Edit this page"
    },
    "chart": {
      "type": "c3"
    },
    "favicon": "/images/favicon.ico",
    "appleTouchIconPrecomposed152": "/images/apple-touch-icon-precomposed-152.png",
    "output": "_book",
    "donate": {
      "wechat": "/images/wechat.jpg",
      "alipay": "/images/alipay.jpg",
      "Title": "reward"
      "Button": "Donate"
      "AlipayText": "Alipay".
      "Wechat Text": "Wechat"
    }
}

structureDirectory structure configuration

AppointREADME.md,SUMMARY.md,GLOSSARY.mdandLANGS.md File name.

Configuration item describe
structure.readme readmeFile name (default value isREADME.md)
structure.summary summaryFile name (default value isSUMMARY.md)
structure.glossary glossaryFile name (default value isGLOSSARY.md)
structure.languages languagesFile name (default value isLANGS.md)

pdfTo configure

CustomizedpdfOutput format, which may require installationebook-convertRelated plug-ins such as

Configuration item describe
pdf.pageNumbers Add a page number (default value istrue )
pdf.fontSize Font size (default value is12 )
pdf.fontFamily Font set (default value isArial )
pdf.paperSize Page size (default value isa4) supporta0,a1,a2,a3,a4,a5,a6,b0,b1,b2,b3,b4,b5,b6,legal,letter
pdf.margin.top Upper boundary (default value is56 )
pdf.margin.bottom Lower boundary (default value is56 )
pdf.margin.left Left boundary (default value is62 )
pdf.margin.right Right boundary (default value is62 )

E-Book Cover Photoscover.jpgandcover_small.jpgIt will be explained in detail later.

GLOSSARY.mdGlossary file [optional]

Vocabulary files, used to explain the whole book’s professional vocabulary, such as hovering the mouse on the professional vocabulary will have corresponding prompts.

Grammatical Format:## + + Professional vocabulary

StudygitbookIt’s better to learn markdown and git first. Do you know their purpose?

Example:

## markdown
Simple and elegant typesetting language, simplified version of `HTML', enhanced version of `TXT', please refer to [https://snowdreams 1006.github.io/markdown/] (https://snowdreams 1006.github.io/markdown/).

## git
Distributed version control system, please refer to [https://snowdreams 1006.github.io/git/] (https://snowdreams 1006.github.io/git/)

LANGS.mdLanguage file [optional]

Support International Book writing, a language with a separate subdirectory, the same language files into the root directory.

Example:

* [English](en/)
* [French](fr/)
* [Español](es/)

Summary of chapters

Development Initial Stage Runninggitbook initOrder according toSUMMARY.mdFile content automatically creates the corresponding directory structure and runs after compiling the contents of each file.gitbook serveStart the local service real-time preview effect.

After a certain degree of development, we intend to publish the service and run it again.gitbook buildOutput to_book/Directory, don’t forget to configurebook.jsonFile, and then you can_book/Throw the entire foldernginxWait for a static server so that you can access your ebook online.

Is it very simple? How to publish and export the related tutorials in the future? Come here today, see you next time! ___________

Recommended Today

Hadoop MapReduce Spark Configuration Item

Scope of application The configuration items covered in this article are mainly for Hadoop 2.x and Spark 2.x. MapReduce Official documents https://hadoop.apache.org/doc…Lower left corner: mapred-default.xml Examples of configuration items name value description mapreduce.job.reduce.slowstart.completedmaps 0.05 Resource requests for Reduce Task will not be made until the percentage of Map Task completed reaches that value. mapreduce.output.fileoutputformat.compress false […]