GitBook 插件配置

注意，GitBook 迭代很快，有些插件可能已经无法使用，尤其是 multipart 这个插件！

这里记录几个常用的插件，其它使用插件的配置参照：

https://gitbook.zhangjikai.com/plugins.html

1. toggle-chapters

toggle-chapters 插件的效果是：默认只在目录导航中显示章的标题，而不会显示小节的标题，点击每一章或者每一节会显示当前章或节的子目录，如果有的话，但是同时会收起其它之前展开的章节。所以个人认为不是非常实用，因为这样子用户不能快速跳转到没有展开的章节。

安装和使用非常简单，参考官方文档即可。

2. codeblock-filenam

codeblock-filename 可以为代码添加一个文件名，以便显示当前代码段属于的文件。

3. Search Plus

支持中文搜索，需要将默认的 search 和 lunr 插件去掉。

插件地址

{
    "plugins": ["-lunr", "-search", "search-plus"]
}

4. Prism

使用 Prism.js 为语法添加高亮显示，需要将 highlight 插件去掉。该插件自带的主题样式较少，可以再安装 prism-themes 插件，里面多提供了几种样式，具体的样式可以参考 这里，在设置样式时要注意设置 css 文件名，而不是样式名。

Prism 插件地址

prism-themes 插件地址

{
    "plugins": [
        "prism",
        "prism-themes",
        "-highlight"
    ],
    "pluginsConfig": {
        "prism": {
            "css": [
                "prism-themes/themes/prism-base16-ateliersulphurpool.light.css"
            ]
        }
    }
}

prism-themes 插件为其提供了许多预设 CSS 文件。如果要预览效果，可以去 prism themes - GitHub。这些预设 CSS 文件均位于 ${yourBookDir}/node_modules/。

如果需要修改背景色、字体大小等，可以在 website.css 定义 pre[class*="language-"] 类来修改，下面是一个示例：

pre[class*="language-"] {
    border: none;
    background-color: #f7f7f7;
    font-size: 1em;
    line-height: 1.2em;
}

5. Advanced Emoji

支持 emoji 表情

emoij 表情列表

插件地址

"plugins": [
    "advanced-emoji"
]

6. GitHub

添加 GitHub 图标

插件地址

"plugins": [
    "github"
],
"pluginsConfig": {
    "github": {
        "url": "https://github.com/zhangjikai"
    }
}

7. Github Buttons

添加项目在 GitHub 上的 star，watch，fork 情况

插件地址

{
    "plugins": [
        "github-buttons"
    ],
    "pluginsConfig": {
        "github-buttons": {
            "repo": "zhangjikai/gitbook-use",
            "types": [
                "star",
                "watch",
                "fork"
            ],
            "size": "small"
        }
    }
}

8. Emphasize

为文字加上底色

插件地址

"plugins": [
    "emphasize"
]

9. Splitter

使侧边栏的宽度可以自由调节

插件地址

"plugins": [
    "splitter"
]

10. Simple-page-toc

自动生成本页的目录结构。另外 GitBook 在处理重复的标题时有些问题，所以尽量不要适用重复的标题。

插件地址

{
    "plugins" : [
        "simple-page-toc"
    ],
    "pluginsConfig": {
        "simple-page-toc": {
            "maxDepth": 3,
            "skipFirstH1": true
        }
    }
}

使用方法: 在需要生成目录的地方加上 <!-- toc -->

11. Anchors

添加 GitHub 风格的锚点样式：

gitbook anchors plugin

插件地址

"plugins" : [ "anchors" ]

12. Anchor-navigation-ex

添加 Toc 到侧边悬浮导航以及回到顶部按钮。需要注意以下两点：

  • 本插件只会提取 h[1-3] 标签作为悬浮导航

  • 只有按照以下顺序嵌套才会被提取

# h1
## h2
### h3
必须要以 h1 开始，直接写 h2 不会被提取
## h2

插件地址

{
    "plugins": [
        "anchor-navigation-ex"
    ],
    "pluginsConfig": {
        "anchor-navigation-ex": {
            "isRewritePageTitle": true,
            "isShowTocTitleIcon": true,
            "tocLevel1Icon": "fa fa-hand-o-right",
            "tocLevel2Icon": "fa fa-hand-o-right",
            "tocLevel3Icon": "fa fa-hand-o-right"
        }
    }
}

如果将 GitBook 的源文件保存到 GitHub 或者其他的仓库上，使用该插件可以链接到当前页的源文件上。

插件地址

"plugins": ["edit-link"],
"pluginsConfig": {
    "edit-link": {
        "base": "https://github.com/USER/REPO/edit/BRANCH",
        "label": "Edit This Page"
    }
}

14. Sitemap-general

生成 sitemap。

插件地址

{
    "plugins": ["sitemap-general"],
    "pluginsConfig": {
        "sitemap-general": {
            "prefix": "http://gitbook.zhangjikai.com"
        }
    }
}

15. Favicon

更改网站的 favicon.ico。

插件地址

{
    "plugins": [
        "favicon"
    ],
    "pluginsConfig": {
        "favicon": {
            "shortcut": "assets/images/favicon.ico",
            "bookmark": "assets/images/favicon.ico",
            "appleTouch": "assets/images/apple-touch-icon.png",
            "appleTouchMore": {
                "120x120": "assets/images/apple-touch-icon-120x120.png",
                "180x180": "assets/images/apple-touch-icon-180x180.png"
            }
        }
    }
}

16. Terminal

模拟终端显示，主要用于显示命令以及多行输出，不过写起来有些麻烦。

插件地址

{
    "plugins": [
        "terminal"
    ],
    "pluginsConfig": {
        "terminal": {
            "copyButtons": true,
            "fade": false,
            "style": "flat"
        }
    }
}

插件现在支持 6 种标签：

  • command: Command "executed" in the terminal.

  • delimiter: Sequence of characters between the prompt and the command.

  • error: Error message.

  • path: Directory path shown in the prompt.

  • prompt: Prompt of the user.

  • warning: Warning message.

标签的使用格式如下所示：

**[<tag_name> 内容]

为了使标签正常工作，需要在代码块的第一行加入 **[termial] 标记，下面是一个完整的示例：

**[terminal]
**[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
Normal output line. Nothing special here...
But...
You can add some colors. What about a warning message?
**[warning [WARNING] The color depends on the theme. Could look normal too]
What about an error message?
**[error [ERROR] This is not the error you are looking for]

效果如下所示：

gitbook terminal preview

terminal 支持下面 5 种样式，如果需要更换样式，在 pluginsConfig 里配置即可。

  • black: Just that good old black terminal everybody loves.

  • classic: Looking for green color font over a black background? This is for you.

  • flat: Oh, flat colors. I love flat colors. Everything looks modern with them.

  • ubuntu: Admit it or not, but Ubuntu have a good looking terminal.

  • white: Make your terminal to blend in with your GitBook.

17. Copy-code-button

为代码块添加复制的按钮。

插件地址

{
    "plugins": ["copy-code-button"]
}

18. Alerts

添加不同 alerts 样式的 blockquotes，目前包含 info, warning, danger 和 success 四种样式。

插件地址

{
    "plugins": ["alerts"]
}

下面是使用示例：

Info styling
> **[info] For info**
>
> Use this for infomation messages.

Warning styling
> **[warning] For warning**
>
> Use this for warning messages.

Danger styling
> **[danger] For danger**
>
> Use this for danger messages.

Success styling
> **[success] For info**
>
> Use this for success messages.

效果如下所示：

  • Info styling

    info

  • Warning styling

    warning

  • Danger styling

    danger

  • Success styling

    success

19. Versions-select

添加版本选择的下拉菜单，针对文档有多个版本的情况。

插件地址

{
    "plugins": [ "versions-select" ],
    "pluginsConfig": {
        "versions": {
            "options": [
                {
                    "value": "http://gitbook.zhangjikai.com",
                    "text": "v3.2.2"
                },
                {
                    "value": "http://gitbook.zhangjikai.com/v2/",
                    "text": "v2.5.4"
                }
            ]
        }
    }
}

我们可以自定义 css 来修改 select 的显示样式：

.versions-select select {
    height: 2em;
    line-height: 2em;
    border-radius: 4px;
    background: #efefef;
}

20. RSS

添加 rss 订阅功能。

插件地址

{
    "plugins": [ "rss" ],
    "pluginsConfig": {
        "rss": {
            "title": "GitBook 使用教程",
            "description": "记录 GitBook 的配置和一些插件的使用",
            "author": "Jikai Zhang",
            "feed_url": "http://gitbook.zhangjikai.com/rss",
            "site_url": "http://gitbook.zhangjikai.com/",
            "managingEditor": "me@zhangjikai.com",
            "webMaster": "me@zhangjikai.com",
            "categories": [
                "gitbook"
            ]
        }
    }
}

21. Include-csv

展示 csv 文件。

插件地址

{
    "plugins": ["include-csv"]
}

使用示例：

{% includeCsv  src="./assets/csv/test.csv", useHeader="true" %} {% endincludeCsv %}

为页面添加页脚。

插件地址

"plugins": [
   "tbfed-pagefooter"
],
"pluginsConfig": {
    "tbfed-pagefooter": {
        "copyright":"Copyright &copy zhangjikai.com 2017",
        "modify_label": "该文件修订时间：",
        "modify_format": "YYYY-MM-DD HH:mm:ss"
    }
}

23. Expandable-chapters-small

使左侧的章节目录可以折叠。

插件地址

plugins: ["expandable-chapters-small"]

24. Sectionx

将页面分块显示，标签的 tag 最好是使用 b 标签，如果使用 h1 - h6 可能会和其他插件冲突。

插件地址

{
    "plugins": [
       "sectionx"
   ],
    "pluginsConfig": {
        "sectionx": {
          "tag": "b"
        }
      }
}

25. GA

Google 统计。

插件地址

"plugins": [
    "ga"
 ],
"pluginsConfig": {
    "ga": {
        "token": "UA-XXXX-Y"
    }
}

26. 3-ba

百度统计。

插件地址

{
    "plugins": ["3-ba"],
    "pluginsConfig": {
        "3-ba": {
            "token": "xxxxxxxx"
        }
    }
}

27. Donate

打赏插件。

插件地址

"plugins": [
    "donate"
],
"pluginsConfig": {
    "donate": {
        "wechat": "https://zhangjikai.com/resource/weixin.png",
        "alipay": "https://zhangjikai.com/resource/alipay.png",
        "title": "",
        "button": "赏",
        "alipayText": "支付宝打赏",
        "wechatText": "微信打赏"
    }
}

28. Sharing-plus

分享当前页面，比默认的 sharing 插件多了一些分享方式。

插件地址

plugins: ["-sharing", "sharing-plus"]

配置:

"pluginsConfig": {
    "sharing": {
       "douban": false,
       "facebook": false,
       "google": true,
       "hatenaBookmark": false,
       "instapaper": false,
       "line": true,
       "linkedin": true,
       "messenger": false,
       "pocket": false,
       "qq": false,
       "qzone": true,
       "stumbleupon": false,
       "twitter": false,
       "viber": false,
       "vk": false,
       "weibo": true,
       "whatsapp": false,
       "all": [
           "facebook", "google", "twitter",
           "weibo", "instapaper", "linkedin",
           "pocket", "stumbleupon"
       ]
   }
}

29. quiz

在页面中添加测验功能。

在 book.json 中添加如下内容：

{
    "plugins": ["quiz"]
}

运行 $ gitbook install。

设置插件配置信息：

"quiz": {
    "labels": {
        "check": "提交答案",
        "showExplanation": "显示解释",
        "showCorrect": "显示正确答案",
        "explanationHeader": "释义"
    },
    "text": {
        "noChosen": "Choose at least one answer",
        "incomplete": "Some correct answers are missing"
    },
    "buttons": {
        "showCorrect": true,
        "showExplanation": true
    }
}

30. folding-chapters

results matching ""

    No results matching ""