We are reconstructing the project recently and need to research the help documents. Gitbook has been used in the previous project for many years. I think it is a little ugly, so I want to find a modern one. But time is limited, but also a baidu, learn from many, here is a little tidy up! I found this article when I first saw it. It was not too old. It said that I had researched vuePress and Gitbook, and I basically followed these two directions.

This article starts with gitbooks.

Base Demo

Install the Gitbook CLI tool globally.

npm install gitbook-cli -g
Copy the code

Then check that gitbook is installed successfully

gitbook -V
Copy the code

The installation is successful if the following appears

Initialize the book catalog

gitbook init
Copy the code

Readme.md is the file to which the default address (/) points after the project is started

The SUMMARY. The md is a directory

Written document

Just paste in the directory structure and summary.md

# Summary

* [Home page] (README.md)
* [introduce] (docs/introduct.md)
* [The first chapter] (docs/chapter1/README.md)
  * [The first section] (docs/chapter1/section1.md)
Copy the code

run

gitbook serve
Copy the code

Open a browserhttp://localhost:4000

The basic Demo is done

other

Multiple languages.

Gitbook supports multiple languages, add a langs. md file in the root directory and support the language on the line, you can refer toLearn GitThis address.And then when it comes in there’s this page, which is kind of ugly, this plug-ingitbook-plugin-multilingual-indexIt says you can customize the multi-language home page.

I didn’t try. I didn’t try to change the language in a dropdown on the page, but NOW I put it in the left menu.

About GitBook full text search.

Originally, gitbook had a bad drawing style, so I investigated the help documents. As a result, before vuepress was finally used, the product suddenly found that Vuepress could not meet their full-text search function, so gitbook was used in the final scheme. Then I went down to see how gitbook full-text search was done.

Whether it’s gitBook’s default search or enhanced search, the principle is the same. Then use jQuery getJSON to read and search the file, as shown in the demo above. The package generates a search_index.json that looks like this.

{"index": {"version":"0.5.12"."fields": [{"name":"title"."boost":10}, {"name":"keywords"."boost":15}, {"name":"body"."boost":1}]."ref":"url"."documentStore": {"store": {". /": ["Home page"]."docs/introduct.html": ["Introduction"]."docs/chapter1/": ["Chapter One"]."docs/chapter1/section1.html": ["1"."Section one"]},"length":4},"tokenStore": {"root": {"1": {"docs": {"docs/chapter1/section1.html": {"ref":"docs/chapter1/section1.html"."tf":1}}},"docs": {},"The first": {"docs": {},"Page": {"docs": {". /": {"ref":". /"."tf":11}}}},"Interface": {"docs": {},"Salt": {"docs": {"docs/introduct.html": {"ref":"docs/introduct.html"."tf":11}}}},"The first": {"docs": {},"一": {"docs": {},"Chapter": {"docs": {"docs/chapter1/": {"ref":"docs/chapter1/"."tf":11}}},"Day": {"docs": {"docs/chapter1/section1.html": {"ref":"docs/chapter1/section1.html"."tf":10}}}}}},"length":5},"corpusTokens": ["1"."Introduction"."Chapter One"."Section one"."Home page"]."pipeline": ["stopWordFilter"."stemmer"]},"store": {". /": {"url":". /"."title":"Home page"."keywords":""."body":"Home page \ n"},"docs/introduct.html": {"url":"docs/introduct.html"."title":"Introduction"."keywords":""."body":"Introduce \ n"},"docs/chapter1/": {"url":"docs/chapter1/"."title":"Chapter One"."keywords":""."body":"Chapter one \n"},"docs/chapter1/section1.html": {"url":"docs/chapter1/section1.html"."title":"Section one"."keywords":""."body":"1-1\n"}}}
Copy the code

And then I looked at this big JSON file in our pre-refactoring project that was 15 megabytes in size

Custom Configuration

This is a basic model, but it doesn’t seem to be very useful to take the basic model directly, for example

  • Search: The default search is not keyword highlighted, so you can disable the default search and change it tosearch-pro
  • Share: the default share is some foreign websites, in the domestic is not very applicable

You can also enhance your document, for example

  • Code duplication
  • Back to the top
  • Directory expansion and collapse
  • Hide the specified element

We can implement some custom configuration through configuration files. We can customize the configuration by creating a new book.json file in the root directory.

My configuration looks like this

{
  "title": "test"."author": "test"."description": "description"."language": "zh-hans"."plugins": [
    "-highlight"."copy-code-button"."search-pro"."-search"."-lunr"."splitter"."-sharing"."anchor-navigation-ex"."expandable-chapters"."back-to-top-button"."splitter"."hide-element"]."pluginsConfig": {
    "anchor-navigation-ex": {
      "showLevel": false."mode": "float"."float": {
        "floatIcon": "fa fa-navicon"."showLevelIcon": false."level1Icon": "fa fa-hand-o-right"."level2Icon": "fa fa-hand-o-right"."level3Icon": "fa fa-hand-o-right"
      },
      "showGoTop": false
    },
    "hide-element": {
      "elements": [".gitbook-link"]}}}Copy the code

More configurations can be found here

Most plugins for Gitbook are called ‘gitbook-plugin’, so you can go to NPM to find it.

Add plugin to gitbook install. This command is slow, so you can install NPM directly at this time. I forgot where I saw that Gitbook install is a slow installation of all the plug-ins used, but I didn’t pay attention to this when installing.

Deployment optimization

The title is not very accurate, I just added a package.json to it so that it can be packaged and deployed on the server. I put the Gitbook dependencies in package.json so I don’t have to install Gitbook globally.

On the package. The json

{
  "name": "Test"."version": "1.0.0"."description": "description"."main": "index.js"."dependencies": {
    "gitbook-cli": "^" 2.3.2."gitbook-plugin-anchor-navigation-ex": "^ 1.0.14"."gitbook-plugin-back-to-top-button": "^ 0.1.4"."gitbook-plugin-baidu-tongji": "^" 1.0.4."gitbook-plugin-collapsible-menu": "^ 1.0.3"."gitbook-plugin-copy-code-button": "^ hundreds." "."gitbook-plugin-donate": "^ 1.0.2"."gitbook-plugin-expandable-chapters": "^ 0.2.0." "."gitbook-plugin-github-buttons": "^ 3.0.0"."gitbook-plugin-hide-element": "^ 0.0.4"."gitbook-plugin-page-toc-button": ^ "while"."gitbook-plugin-search-pro": "^ 2.0.2"."gitbook-plugin-splitter": "^ 0.0.8"."gitbook-plugin-tbfed-pagefooter": "^ 0.0.1." "
  },
  "devDependencies": {},
  "scripts": {
    "start": "gitbook serve"."build": "gitbook build"
  },
  "repository": {
    "type": "git"."url": "xxxxxx"
  },
  "keywords": [
    "help"]."author": "Xu"."license": "ISC"
}

Copy the code

Reference links:

  1. The Leader asked me to do the technology selection of CMS help center, I combined VuePress and GitBook, and then selected…
  2. ChengWei’s Blogs
  3. Gitbook use and book.json detailed configuration