Gitbook 的使用和常用插件

赵达

Gitbook 是基于 Node.js 的命令行工具,用来创建漂亮的电子书,它使用 Markdown 或 AsciiDoc 语法来撰写内容,用 Git 进行版本控制,且可以托管在 Github 上。Gitbook 可以将作品编译成网站、 PDF、 ePub 和 MOBI 等多重格式。

如果你不擅长自己搭建 gitbook 环境,还可以使用 gitbook.com 在线服务来创建和托管你的作品,他们还提供了基于桌面的编辑器

如何使用

首先在全局安装 gitbook 客户端工具:

$ npm install gitbook-cli -g

然后在你的作品目录中创建两个必需的文件 README.md 和 SUMMARY.md,README.md 是作品的介绍,SUMMARY.md 是作品的目录结构,里面要包含一个章节标题和文件索引的列表:

# Summary

This is the summary of my book.

* [section 1](section1/README.md)
    * [example 1](section1/example1.md)
    * [example 2](section1/example2.md)
* [section 2](section2/README.md)
    * [example 1](section2/example1.md)

根据 SUMMARY.md 的目录结构初始化各个章节文件:

$ gitbook init

运行服务,在编辑内容后实时预览:

$ gitbook serve

服务器启动后,浏览器打开 http://localhost:4000 查看,撰写完后可以生成静态网站用来发布:

$ gitbook build

使用插件

Gitbook 本身功能丰富,但同时可以使用插件来进行个性化定制。Gitbook 插件 里已经有100多个插件,可以在 book.json 文件的 pluginspluginsConfig 字段添加插件及相关配置,添加后别忘了进行安装。

// book.json
{
  "title": "Webpack 中文指南",
  "description": "Webpack 是当下最热门的前端资源模块化管理和打包工具,本书大部分内容翻译自 Webpack 官网。",
  "language": "zh",
  "plugins": [
    "disqus",
    "github",
    "editlink",
    "prism",
    "-highlight",
    "baidu",
    "splitter",
    "sitemap"
  ],
  "pluginsConfig": {
    "disqus": {
      "shortName": "webpack-handbook"
    },
    "github": {
      "url": "https://github.com/zhaoda/webpack-handbook"
    },
    "editlink": {
      "base": "https://github.com/zhaoda/webpack-handbook/blob/master/content",
      "label": "编辑本页"
    },
    "baidu": {
        "token": "a9787f0ab45d5e237bab522431d0a7ec"
    },
    "sitemap": {
        "hostname": "http://zhaoda.net/"
    }
  }
}
# 安装插件
$ gitbook install ./

常用插件

内容顶部显示 编辑本页 链接。

在每个页面顶部和底部添加广告或任何自定义内容。

splitter

在左侧目录和右侧内容之间添加一个可以拖拽的栏,用来调整两边的宽度。

image-captions

抓取内容中图片的 alttitle 属性,在图片下面显示标题。

github

在右上角显示 github 仓库的图标链接。

anchors

标题带有 github 样式的锚点。

chart

使用 C3.js 图表。

styles-sass

使用 SASS 替换 CSS。

styles-less

使用 LESS 替换 CSS。

ga

添加 Google 统计代码。

disqus

添加 disqus 评论插件。

sitemap

生成站点地图。

latex-codecogs

使用数学方程式。

mermaid

使用流程图。

book-summary-scroll-position-saver

自动保存左侧目录区域导航条的位置。

sharing

默认的分享插件。

fontsettings

默认的字体、字号、颜色设置插件。

默认搜索插件。

自定义页脚,显示版权和最后修订时间。

prism

基于 Prism 的代码高亮。

atoc

插入 TOC 目录。

ace

插入代码高亮编辑器。

highlight

默认的代码高亮插件,通常会使用 prism 来替换。

github-buttons

显示 github 仓库的 star 和 fork 按钮。

sectionx

分离各个段落,并提供一个展开收起的按钮。

mcqx

使用选择题。

include-codeblock

通过引用文件插入代码。

fbqx

使用填空题。

spoiler

隐藏答案,当鼠标划过时才显示。

anchor-navigation

锚点导航。

youtubex

插入 YouTube 视频。

redirect

页面跳转。

expandable-chapters

收起或展开章节目录中的父节点。

baidu

使用百度统计。

duoshuo

使用多说评论。

jsfiddle

插入 JSFiddle 组件。

jsbin

插入 JSBin 组件。

开发插件

最好先查看别人的插件是怎么做的,然后再看官方文档

返回首页