刘琛运的技术文档

Appearance

插件 ​

新建book.json ​

1635939342239

安装插件 ​

配置完book.json,执行命令

gitbook install

设置book.json ​

通用配置 ​

title ​

设置书本的标题

"title" : "my book"

author ​

作者的相关信息

"author" : "liuchenyun"

description ​

本书的简单描述

"description" : "整理文档"

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" : "2.6.4",

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

js
"links" : {
    "sidebar" : {
        "Home" : "https://www.bilibili.com/"
    }
}

styles ​

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

js
"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中设置

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

plugins ​

配置使用的插件

js
"plugins": [
    "disqus"
]

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

Gitbook默认带有5个插件：

  • highlight
  • search
  • sharing
  • font-settings
  • livereload

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

"plugins": [js
    "-search"
]

pluginsConfig ​

配置插件的属性

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

structure ​

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

变量含义和默认值
structure.readmeReadme file name (defaults to README.md)
structure.summarySummary file name (defaults to SUMMARY.md)
structure.glossaryGlossary file name (defaults to GLOSSARY.md)
structure.languagesLanguages file name (defaults to LANGS.md)

我的配置

js
{
    "title" : "知识之书",
    "author" : "刘琛运",
    "description" : "通往真理之境",
    "language" : "zh-hans",
    "links" : {
        "sidebar" : {
            "Home" : "https://www.baidu.com"
        }
    }
}

###常用插件

高级搜索 ​

支持中文搜索, 在使用此插件之前，需要将默认的search和lunr 插件去掉。

js
"plugins": [
         "-lunr", "-search", "search-pro"
 ]

目录折叠 ​

下面两个组合使用

Expandable-chapters-small⭐⭐⭐⭐⭐

点击箭头实现折叠扩展

js
"plugins": [
    "expandable-chapters-small"
]

chapter-fold ⭐⭐⭐⭐⭐

点击导航栏的标题名实现折叠扩展

js
"plugins": [
    "chapter-fold"
]

侧边栏调节 ​

Splitter⭐⭐⭐⭐⭐

侧边栏自由调节

js
"plugins": [
    "splitter"
]

代码复制.行号 ​

code⭐⭐⭐⭐⭐

为代码块添加行号和复制按钮，复制按钮设置false可关闭

js
{
    "plugins" : [ 
        "code" 
    ]
}
"pluginsConfig": {
     "code": {
          "copyButtons": true
      }
}

页脚及版权信息 ​

tbfed-pagefooter⭐⭐⭐⭐⭐

js
"plugins": [
       "tbfed-pagefooter"
],
 "pluginsConfig": {
     "tbfed-pagefooter": {
	        "copyright":"Copyright &copy liuchenyun.com 2020-2024",
	        "modify_label": "作者：",
	        "modify_format": "刘琛运"
      }
 }

还有page-copyright插件可以显示更多页脚及版权信息

悬浮导航及回到顶部 ​

Anchor-navigation-ex⭐⭐⭐⭐

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

  • 本插件只会提取 h[1-3] 标签作为悬浮导航
  • 只有按照以下顺序嵌套才会被提取
  • 版本有些低，启动有错误信息
  • 对需要导航的标题设置 h[1-3]，h4看情况用
  • 会自动生成1、1.1、1.1.1标题层级，无需自己再设置
# h1
## h2
### h3
必须要以 h1 开始，直接写 h2 不会被提取
js
{
    "plugins": [
        "anchor-navigation-ex"
    ],
    "pluginsConfig": {
        "anchor-navigation-ex": {
            "isShowTocTitleIcon": true,
            "tocLevel1Icon": "fa fa-hand-o-right",
            "tocLevel2Icon": "fa fa-hand-o-right",
            "tocLevel3Icon": "fa fa-hand-o-right"
        }
    }
}

查看图片 ​

下面2个不能同时用，优先级lightbox >popup

lightbox ⭐⭐⭐⭐

打开图片查看

js
{
  "plugins": [
      "lightbox"
  ]
}

popup ⭐

单击图片，在新页面查看大图（跟点击图片右键，选择在新标签中打开效果一样）

js
{
  "plugins": [ 
      "popup"
  ]
}

图表 ​

Chart⭐⭐⭐⭐

使用 C3.js 或者 Highcharts 绘制图形。

C3.js highcharts

js
{
    "plugins": [ "chart" ],
    "pluginsConfig": {
        "chart": {
            "type": "c3"
        }
    }
}
js
下面是一个示例：
{% chart %}
{
    "data": {
        "type": "bar",
        "columns": [
            ["data1", 30, 200, 100, 400, 150, 250],
            ["data2", 50, 20, 10, 40, 15, 25]
        ],
        "axes": {
            "data2": "y2"
        }
    },
    "axis": {
        "y2": {
            "show": true
        }
    }
}
{% endchart %}

视频 ​

Local Video⭐⭐⭐⭐

使用Video.js 播放本地视频

js
"plugins": [ 
    "local-video" 
]

使用示例：为了使视频可以自适应，我们指定视频的width为100%，并设置宽高比为16:9，如下面所示

html
<video id="my-video" class="video-js" controls preload="auto" width="100%"
poster="https://zhangjikai.com/resource/poster.jpg" data-setup='{"aspectRatio":"16:9"}'>
  <source src="https://zhangjikai.com/resource/demo.mp4" type='video/mp4' >
  <p class="vjs-no-js">
    To view this video please enable JavaScript, and consider upgrading to a web browser that
    <a href="http://videojs.com/html5-video-support/" target="_blank">supports HTML5 video</a>
  </p>
</video>

另外我们还要再配置下css，即在website.css中加入

css
.video-js {
    width:100%;
    height: 100%;
}
这里的地址http://localhost:4000，尽量不要把视频放在本地，放在第三方里方便设置

阅读量 ​

pageview-count⭐⭐⭐

  • 左上角增加阅读量计数
  • 每次重启服务会清零
js
{
    "plugins": [
        "pageview-count"
    ]
}

表格滚动条 ​

auto-scroll-table⭐⭐⭐

为避免表格过宽，增加滚动条

js
{
     "plugins": [
         "auto-scroll-table"
     ]
}

github风格锚点 ​

Anchors⭐⭐⭐

添加 Github 风格的锚点样式

1636033463778

js
"plugins" : [ 
    "anchors" 
]

隐藏元素 ​

hide-element⭐⭐⭐

这里我们隐藏gitbook链接

js
{
    "plugins": [
        "hide-element"
    ],
    "pluginsConfig": {
        "hide-element": {
            "elements": [".gitbook-link"]
        }
    }
}

1636792150782

​

Mermaid图表 ​

目前这个 Mermaid 主要可支持的「绘图」有：

  • 流图 （Flow）
  • 序列图 （Sequence）
  • 甘特图（Gantt）
  • 类图（Class）
  • 状态迁移图（State）
  • 饼分图（Pie）

注意：不是所有的 Markdown 编辑器都支持所有的绘图类型 ，至少会支持 「流图」和「序列图」

github:https://github.com/mermaid-js/mermaid

mermaid⭐⭐⭐

js
"plugins" : [ 
    "mermaid-gb3" 
]
​```mermaid
graph TD
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
​```
可以不用```mermaid```包括起来，但需要选择语言mermaid
mermaid
graph TD
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

目录结构 ​

Simple-page-toc⭐⭐

自动生成本页的目录结构。

  • 不适用重复的标题
  • 不支持中文的标题跳转
  • 与悬浮导航功能重复
js
{
    "plugins" : [
        "simple-page-toc"
    ],
    "pluginsConfig": {
        "simple-page-toc": {
            "maxDepth": 3,
            "skipFirstH1": true
        }
    }
}
整个文件包括起来

打赏插件 ​

donate⭐⭐

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

​

导航栏图片 ​

insert-logo⭐⭐

可以添加公司的logo在左上角

js
{
  "plugins": [
       "insert-logo"
  ],
  "pluginsConfig": {
    "insert-logo": {
      "url": "assets/1git初始目录结构.png",
      "style": "background: none; max-height: 30px; min-height: 30px"
    }
  }
}

1636793686148

csv文件 ​

Include-csv⭐⭐

csv 文件

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

使用示例：

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

emoji表情 ​

advanced-emoji⭐⭐

支持emoji表情

emoij表情列表

js
"plugins": [
    "advanced-emoji"
]

使用示例：

😀 😂

分享 ​

Sharing-plus⭐⭐

分享加强更多，比默认的 sharing 插件多了一些分享方式。

js
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"
       ]
   }
}

​

文字颜色 ​

Emphasize⭐⭐

为文字加上底色

css
  This text is {% em %}highlighted !{% endem %}
  This text is {% em %}highlighted with **markdown**!{% endem %}
  This text is {% em type="green" %}highlighted in green!{% endem %}
  This text is {% em type="red" %}highlighted in red!{% endem %}
  This text is {% em color="#ff0000" %}highlighted with a custom color!{% endem %}

网站图标 ​

Favicon⭐

更改网站的 favicon.ico

js
{
    "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"
            }
        }
    }
}

背景切换 ​

change_girls⭐

背景可以切换，时间的间隔有些问题，不太好用

js
{
    "plugins":[
        "change_girls"
    ]
    "pluginsConfig": {
       "change_girls" : {
            "time" : 3,
            "urls" : [
                "http://localhost:4000/gitbook/assets/1635953039042.png", 
                "http://localhost:4000/gitbook/assets/1635939342239.png",
                "http://localhost:4000/gitbook/assets/1636033463778.png"
            ]
        }
    }
}
time：图片的切换时间，单位是秒
urls： 一个数组，可以定义多个图片

多版本选择 ​

Versions-select

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

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

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

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

1635953039042

参考资料：http://gitbook.zhangjikai.com/plugins.html#expandable-chapters-small