gitbook 入門教程之主題插件

時間 2019-11-17

標籤 gitbook 入門教程主題插件欄目 Git 简体版

原文原文鏈接

主題插件

目前 gitbook 提供三類文檔: Book 文檔,API 文檔和 FAQ 文檔.html

其中,默認的也是最常使用的就是 Book 文檔,若是想要了解其餘兩種文檔模式,須要引入相應的主題插件.git

官方主題插件文檔: https://toolchain.gitbook.com/themes/github

Book 文檔

theme-default 主題

插件地址: https://plugins.gitbook.com/plugin/theme-defaultweb

theme-default 是 3.0.0 引入的默認主題,大多數插件針對的都是默認主題,若是切換到其餘主題或者自定義主題,可能會形成某些狀況下不兼容,甚至報錯.json

默認狀況下,左側菜單不顯示層級屬性,若是將 showLevel 屬性設置爲 true 能夠顯示層級數字.api

示例:app

"pluginsConfig": {
    "theme-default": {
        "showLevel": true
    }
}

效果:ide

默認狀況下左側菜單樹不顯示目錄層級工具

開啓層級顯示設置後,左側菜單樹顯示當前目錄層級網站

theme-comscore 主題

插件地址: https://plugins.gitbook.com/plugin/theme-comscore

default 默認主題是黑白的,而 comscore 主題是彩色的,即標題和正文顏色有所區分.

示例:

"plugins": [
   "theme-comscore"
]

效果:

默認狀況下各級標題顏色均是黑色,不一樣級別的標題僅僅是大小區別.

設置 comscore 主題後,各級標題顏色不一樣,不單單是大小不一樣.

API 文檔

theme-api 插件

插件地址: https://plugins.gitbook.com/plugin/theme-api

若是文檔自己是普普通文檔模式,切換成 api 文檔模式後並不會有太大變化,除非一開始就是接口文檔,那樣使用 theme-api 插件才能看出效果.

示例:

{
    "plugins": ["theme-api"],
    "pluginsConfig": {
        "theme-api": {
            "theme": "dark"
        }
    }
}

語法:

方法區

{% method %}
    方法區: 接口說明
{% endmethod %}

語法區

{% sample lang="特定語言" %}

{% common %}

示例:

{% method -%}
## Simple method

{% sample lang="js" -%}
This text will only appear for JavaScript.

{% sample lang="go" -%}
This text will only appear for Go.

{% common -%}
This will appear for both JavaScript and Go.
{% endmethod %}

效果:

添加 api 相關方法後的文檔效果,正常會兩列顯示並在右上角增長語言切換工具.

FAQ 文檔

theme-faq 插件

插件地址: https://plugins.gitbook.com/plugin/theme-faq

theme-faq 能夠幫助咱們構建問答中心,預設好常見問題以及相應答案模式,同時爲了方便搜索到問題或答案,通常須要搜索插件的配合.

示例:

{
    "plugins": [
        "theme-faq",
        "-fontsettings",
        "-sharing",
        "-search", 
        "search-plus"
    ]
}

幫助中心沒有工具欄,所以涉及到工具類的插件一概失效或主動移除,同時默認搜索插件也會失效.

語法:

增長文章間的關聯

---
related:
    - some/other/page.md
    - another_related_article.md
 
---
 
Content of my article!

在當前頁面底部顯示延伸閱讀,支持 yaml 語法關聯到其餘頁面.

增長頭部 logo

{% extends template.self %}
 
{% block faq_header_brand %}
<img src="https://mywebsite.com/logo.png" height="30" />
{% endblock %}

新建 _layouts/website/page.html 文件,用於擴展當前主題插件來增長自定義 logo.

增長導航欄連接

{% extends template.self %}
 
{% block faq_menu %}
<ul class="nav navbar-nav navbar-right">
    <li><a href="#">Contact us</a></li>
    <li><a href="#">Return to SuperWebsite</a></li>
</ul>
{% endblock %}

新建 _layouts/website/page.html 文件,用於擴展當前主題插件來增長自定義導航欄連接.

示例:

{% extends template.self %}
 
{% block faq_header_brand %}
<img src="https://upload.jianshu.io/users/upload_avatars/16648241/57aebe62-b5b5-491a-a9fd-f994d5be7dda.jpg?imageMogr2/auto-orient/strip|imageView2/1/w/240/h/240" />
{% endblock %}

{% extends template.self %}
 
{% block faq_menu %}
<ul class="nav navbar-nav navbar-right">
    <li><a href="https://snowdreams1006.github.io/other/me.html">聯繫我</a></li>
    <li><a href="https://snowdreams1006.github.io/">返回主頁</a></li>
</ul>
{% endblock %}