主題插件
目前 gitbook 提供三類文檔: Book 文檔,API 文檔和 FAQ 文檔.
其中,默認的也是最常使用的就是 Book 文檔,如果想要了解其他兩種文檔模式,需要引入相應的主題插件.
Book 文檔
theme-default 主題
theme-default 是 3.0.0 引入的默認主題,大多數插件針對的都是默認主題,如果切換到其他主題或者自定義主題,可能會造成某些情況下不兼容,甚至報錯.
默認情況下,左側菜單不顯示層級屬性,如果將 showLevel 屬性設置為 true 可以顯示層級數字.
示例:
"pluginsConfig": {
"theme-default": {
"showLevel": true
}
}
效果:
默認情況下左側菜單樹不顯示目錄層級
開啟層級顯示設置后,左側菜單樹顯示當前目錄層級
theme-comscore 主題
default 默認主題是黑白的,而 comscore 主題是彩色的,即標題和正文顏色有所區分.
示例:
"plugins": [
"theme-comscore"
]
效果:
默認情況下各級標題顏色均是黑色,不同級別的標題僅僅是大小區別.
設置
comscore主題后,各級標題顏色不同,不僅僅是大小不同.
API 文檔
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 插件
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 %}
新建
_layouts/website/page.html文件,增加自定義logo和導航欄鏈接.
效果:
小結
本節主要講解了常用的三種文檔模式,其中 default 主題插件,適合一般的博客類網站或靜態網站,api 主題插件適合接口文檔的編寫,faq 主題插件則適合幫助中心.
三種主題插件分別對應不同的應用場景,默認情況下使用的是 default 主題插件,平時介紹的大多數功能插件也大多適合這種主題,另外兩種主題可能就不能很好兼容第三方插件,需要親身體驗.