Hello, I’m Yue Chuang.

First blog: www.aiyc.top/1947.html

Official account: AI Yue Chuang

Detailed record step by step to build their own electronic document notes

1. Environment construction

1.1 installation Nodejs

There is no problem with this sentence:

The installation is simple, just download it and go next. Download link: nodejs.org/en/

Small white continue to look down:

Official packages for all major platforms are available at nodejs.cn/download/

One of the easiest ways to install Node.js is through the package manager. For this, each operating system has its own package manager.

Homebrew is the industry standard on macOS and it is very easy to install Node.js after installation (by running the following command on the CLI) :

brew install node
Copy the code

Other package managers for Linux and Windows are listed at nodejs.org/en/download… .

NVM is a popular way to run Node.js. For example, it can easily switch node.js versions, or install new versions to try and easily roll back when problems occur.

This is useful for testing code with older versions of Node.js.

See github.com/creationix/… .

It is recommended that if you are just getting started and haven’t used Homebrew before, use the official installer, otherwise Homebrew is a better solution.

However, once node.js is installed, you can access the Node executable from the command line.

1.2 Gitbook – CLI scaffolding installation

  1. Command to install
npm install -g gitbook-cli
Copy the code
  1. Version of the validation
# gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3
Copy the code

  1. Compiler choice: The following two are recommended

  2. vscode

  3. Typora

  4. sublimeText3

2. Create a directory and initialize it

mkdirGitbook-imsdk // Create project directorycdGitbook -imsdk gitbook init // Initialize the directoryCopy the code

PS: If initialization error:

TypeError [ERR_INVALID_ARG_TYPE]: The "data" argument must be of type string or an instance of Buffer, TypedArray, or DataView. Received an instance of Promise
Copy the code

The node version is too high. You can lower the NodeJS version. But need to reinstall? You can reinstall it, but it’s not cost-effective or technical. To see what NVM is, click on this article to read: NVM common commands

NVM list NVM use VXXXX and go to CD gitbook-imsdk gitbook initCopy the code

PS:

# nvm list

  * 14.18.0 (Currently using 64-bit executable)
    10.12.0

# nvm use v10.12.0
Now using node v10.12.0 (64-bit)
Copy the code

After initialization, two files are generated by default: summary. md and readme.md

3. Elaborate

3.1 Writing README and SUMMARY

If we want to add chapter directories for our creation, we can use sumary.md file to divide chapter directories. The format of this file is also relatively simple, for example:

3.1.1 README, md

This file is equivalent to an introduction to a Gitbook, such as our readme.md:

# Gitbook getting started


> GitBook is a Command line tool based on Node.js that uses Github/Git and Markdown to create beautiful ebooks.This book will briefly introduce how to install, write, generate, and publish an online book.Copy the code

3.1.2 the SUMMARY. The md

This file is the equivalent of a book directory structure. For example, the SUMMARY. Md of our book:

# Summary

* [Introduction] (README.md)
* [Basic installation] (howtouse/README.md)
   * [Node. Js installed] (howtouse/nodejsinstall.md)
   * [Gitbook installation] (howtouse/gitbookinstall.md)
   * [Gitbook Command line view] (howtouse/gitbookcli.md)
* [Book Project structure] (book/README.md)
   * [Readme. md and SUMMARY writing] (book/file.md)
   * [Directory initialization] (book/prjinit.md)
* [The book output] (output/README.md)
   * [The output is a static website] (output/outfile.md)
   * [The output PDF] (output/pdfandebook.md)
* [release] (publish/README.md)
   * [Publish to Github Pages] (publish/gitpages.md)
* [The end of the] (end/README.md)
Copy the code

Summary. md is basically a list plus link syntax. Directories can be used in links, as well as in links.

3.2 Local Preview

3.2.1 gitbook init

Before we preview, we need to do one more step.

Once readme. md and summary. md are created, we can use Gitbook’s command line tools to generate directories and files from this directory structure

$ls Readme.md summary.md book end howtouse Output Publish $tree.├ ── Readme.md ├─ School exercises ── Class exercises ── Class Exercises ── Class Exercises ── Class Exercises ── Class Exercises ── Class Exercises ── Class Exercises ── Class Exercises ── Class Exercises ── class Exercises ── class Exercises ├ ─ ─ gitbookcli. Md │ └ ─ ─ gitbookinstall. Md ├ ─ ─ the output │ ├ ─ ─ the README. Md │ ├ ─ ─ outfile. Md │ └ ─ ─ pdfandebook. Md └ ─ ─ the publish ├ ─ ─ the README. Md └ ─ ─ gitpages, mdCopy the code

As you can see, Gitbook gives us the directories and files that correspond to summary.md.

In each directory, there is a readme.md file that describes the instructions for this chapter.

3.2.2 gitbook serve

Next, we use

gitbook serve ./{book_name}
Copy the code

My operation, start service, preview:

gitbook serve
Copy the code

After starting, type http://localhost:4000 in your browser

Note:

You can create the article directory in advance, automatically generate the corresponding file by executing Gitbook Init, and then serve it in Gitbook.

3.3 Book Output

So far, Gitbook supports the following output:

  • Static HTML, you can think of it as a static website
  • PDF format
  • EBook format
  • Single HTML file
  • JSON format

Let’s focus on how to export static HTML and PDF files.

3.3.1 Output as static website

You can output a static site in two ways:

1. The local preview is automatically generated

Once you’ve edited the Gitbook document, you can use gitbook’s commands to preview it locally.

gitbook serve ./{book_name}
Copy the code

The Gitbook launches a 4000 port for preview.

For example, preview the document with a Gitbook Serve:

clela@AIYC D:\gitee_all\quicksand_suanfa
# 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 14 pages
info: found 13 asset files
info: > >generation finished with success in 1.0s !

Starting server.Serving book on http: / /localhost: 4000Copy the code

You can open this website in your browser: http://localhost:4000

You will notice that there is an extra _book directory in the directory of the Gitbook project that you are editing, and this directory is the static site content that is generated for the local preview.

2. Use the gitbook build parameter

Using this command, you can export the content to the desired directory, as opposed to the static site generated by direct preview.

Ps: /{book_name} –output=./{outputFolde} gitbook build [current path] [output path] gitbook build In the doc folder

$ gitbook build --output=/tmp/gitbook
Starting build ...
Successfuly built !
$ ls /tmp/gitbook/
howtouse          search_index.json
book              imgs              output
gitbook           index.html        publish
Copy the code

Note:

Once packaged, the default output file is placed in the _book folder, the compiled entry: index.html

Either way, you can package the static site and publish it to the server you want to publish it to, or you can package it directly to readers.

3.3.2 rainfall distribution on 10-12 output PDF

Output as a PDF file, you need to install gitbook PDF first

npm install gitbook-pdf -g
Copy the code

In general, it is not recommended to install a global environment; it is better to install a local environment.

If downloading the PhantomJS package takes too long while installing Gitbook-PDF, you can download it from the Official PhantomJS website. See the documentation on phantomjs.org/ for how to install the package.

Of course, I tried the above method and failed. So I took a different approach.

In Windows, use Gitbook to generate PDF files: www.aiyc.top/1969.html

Then, you can generate a PDF file with the following command.

gitbook pdf {book_name}
Copy the code

If you are already writing the current directory of Gitbook, you can also use relative paths.

gitbook pdf .
Copy the code

You will then notice that you have an extra file named book.pdf in your directory.

3.4 Viewing Help

clela@AIYC D:\gitee_all\quicksand_suanfa
# gitbook -h

  Usage: gitbook [options] [command]


  Options:

    -v, --gitbook [version]  specify GitBook version to use
    -d, --debug              enable verbose error
    -V, --version            Display running versions of gitbook and gitbook-cli
    -h, --help               output usage information


  Commands:

    ls                        List versions installed locally
    current                   Display currently activated version
    ls-remote                 List remote versions available for install
    fetch [version]           Download and install a <version>
    alias [folder] [version]  Set an alias named <version> pointing to <folder>
    uninstall [version]       Uninstall a version
    update [tag]              Update to the latest version of GitBook
    help                      List commands for GitBook
    *                         run a command with a specific gitbook version
Copy the code

3.5 release

Github Pages can be used to publish our Gitbook on the Internet, if you already know how to use Git, Github and Github Pages.

3.5.1 Publishing to Github Pages

1. Publish static websites directly to Github Pages

You can process a written.md file through Gitbook into a static web site and publish it to Github Pages.

This reference this: [www.yuque.com/docs/share/… the use of making from scratch to build a blog] (www.yuque.com/docs/share/… Build a blog from scratch on GitHub)

3.5.2 Using the Pages service of the project

In addition to the above method of publishing static files directly to Github Pages, you can also use the Github Pages feature for a separate project.

1. Create warehouses and branches

  1. Log on to Github and create a new repository, which we’ll callbookSo I get onebookThe warehouse. (When creating xiaobai recommended to selectREADME.mdInitialization)
  2. Clone repository to local:git clone [email protected]:/USER_NAME/book.git
  3. Create a new branch:git checkout -b gh-pages, note that the branch name must begh-pages 。
  4. Push the branch to the repository:git push -u origin gh-pages.
  5. Switch to the main branch:git checkout main.

After this step, we have created the GH-Pages branch, with which Github will automatically assign you a URL.

USERNAME.github.io/book

Synchronize static site code to branch:

Now we can sync our built static website code into the GH-Pages branch.

Copy the successful build file to the Book folder in the book directory.

  1. Switching Git branches
Git checkout (gh-pages) # git checkout (gh-pagesCopy the code

My actual operation:

aiyc@aiyc:/mnt/d/Github_pages/book$ git checkout gh-pages
Switched to branch 'gh-pages'
Your branch is up to date with 'origin/gh-pages'.
Copy the code

Next, enter the following series of commands:

git add .
git commit -m "first commit"
git push
Copy the code

Then, after ten minutes or so, you will have access to your online book. In the future, as long as you change each time, will generate static site Copy to the book directory, and then run the above three commands once OK.

We will update the usage of the plugin later, so stay tuned!

AI Yue Chuang ·V: Jiabcdefh