主要记录GitBook的安装配置以及一些插件信息

http://gitbook.zhangjikai.com/

GitBook安装

下面介绍在本地如何安装 GitBook，如果不需要本地调试 & 不需要获得生成的 html 文件，可以直接使用官网提供的服务。

环境要求

NodeJS(v4.0.0及以上)

通过NPM安装

运行下面的命令进行安装

npm install gitbook-cli -g

其中gitbook-cli是gitbook的一个命令行工具, 通过它可以在电脑上安装和管理gitbook的多个版本.

编辑书籍

gitbook 官方已经提供了一个本地的编辑器, 使用它可以方便的编写书籍(不需要手动的写SUMMARY.md), 并且支持windows、mac、linux 三种平台, 所以强烈建议使用编辑器编写书籍.

预览书籍

使用下列命令会运行一个服务器, 通过http://localhost:4000/可以预览书籍

gitbook serve

运行该命令后会在书籍的文件夹中生成一个 _book 文件夹, 里面的内容即为生成的 html 文件. 我们可以使用下面命令来生成网页而不开启服务器

gitbook build

GitBook 基本的目录结构如下所示

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

这里主要讲下 GitBook 预定义的几个文件的作用

book.json

存放配置信息，在下一章中所讲的配置信息都是在这个文件里定义的，关于该文件的配置可以看配置这个章节。

Summary

概要文件主要存放 GitBook 的文件目录信息，左侧的目录就是根据这个文件来生成的，默认对应的文件是 SUMMARY.md，可以在 book.json 重新定义该文件的对应值。它通过 Markdown 中的列表语法来表示文件的父子关系，下面是一个简单的示例：

# 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)

这个配置对应的目录结构如下所示:

我们通过使用标题或者水平分割线标志将 GitBook 分为几个不同的部分

# 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)

这个配置对应的目录结构如下所示：

Glossary

词汇表文件，默认对应的文件是 GLOSSARY.md。该文件主要存储词汇信息，如果在其他页面中出现了该文件中的词汇，鼠标放到词汇上会给出词汇示意，可以将鼠标移到下面两个词汇上看下效果。

Git Markdown

Glossary 文件的格式如下所示：

## Git
分散式版本控制软件

## Markdown
Aaron Swartz 跟John Gruber共同设计的排版语言

GitBook配置

记录Gitbook的一些配置信息

title

设置书本的标题

"title" : "Gitbook Use"

author

作者的相关信息

"author" : "zhangjikai"

description

本书的简单描述

"description" : "记录Gitbook的配置和一些插件的使用"

language

Gitbook使用的语言, 版本2.6.4中可选的语言如下：

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

配置使用简体中文

"language" : "zh-hans",

gitbook

指定使用的gitbook版本

"gitbook" : "3.2.2",
"gitbook" : ">=3.0.0"

root

指定存放 GitBook 文件（除了 book.json）的根目录

"root": "."

links

在左侧导航栏添加链接信息

"links" : {
    "sidebar" : {
        "Home" : "http://zhangjikai.com"
    }
}

styles

自定义页面样式，默认情况下各generator对应的css文件

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

例如使<h1> <h2>标签有下边框，可以在website.css中设置

h1 , h2{
    border-bottom: 1px solid #EFEAEA;
}

plugins

配置使用的插件

"plugins": [
    "disqus"
]

添加新插件之后需要运行gitbook install来安装新的插件

Gitbook默认带有5个插件：

highlight
search
sharing
font-settings
livereload

如果要去除自带的插件，可以在插件名称前面加-

"plugins": [
    "-search"
]

pluginsConfig

配置插件的属性

"pluginsConfig": {
    "fontsettings": {
        "theme": "sepia",
        "family": "serif",
        "size":  1
    }
}

structure

指定 Readme、Summary、Glossary 和 Languages 对应的文件名，下面是这几个文件对应变量以及默认值：

变量	含义和默认值
`structure.readme`	`Readme file name (defaults to README.md)`
`structure.summary`	`Summary file name (defaults to SUMMARY.md)`
`structure.glossary`	`Glossary file name (defaults to GLOSSARY.md)`
`structure.languages`	`Languages file name (defaults to LANGS.md)`

GitBook 插件

记录一些实用的插件, 如果要指定插件的版本可以使用 plugin@0.3.1。下面的插件在 GitBook 的 3.2.3 版本中可以正常工作，因为一些插件可能不会随着 GitBook 版本的升级而升级，即下面的插件可能不适用高版本的 GitBook，所以这里指定了 GitBook 的版本。另外本文记录的插件在 Linux 下都是可以正确工作的，windows 系统没有测试。这里只是列举了一部分插件，如果有其它的需求，可以到插件官网区搜索相关插件。

posted on 2021-11-25 21:03 我尽量尽力而为阅读(354) 评论(0) 编辑收藏举报

刷新页面返回顶部

我尽量尽力而为