![a6173fb5b833cd9484a101ce5d9c8fe6.png](https://i-blog.csdnimg.cn/blog_migrate/f658b070036fcfbdfb561e0c04ae7bf5.jpeg)
目前 gitbook 提供三类文档: Book 文档,API 文档和 FAQ 文档.
其中,默认的也是最常使用的就是 Book 文档,如果想要了解其他两种文档模式,需要引入相应的主题插件.
官方主题插件文档:
https://toolchain.gitbook.com/themes/
Book 文档
theme-default 主题
插件地址:
https://plugins.gitbook.com/plugin/theme-default
theme-default 是 3.0.0 引入的默认主题,大多数插件针对的都是默认主题,如果切换到其他主题或者自定义主题,可能会造成某些情况下不兼容,甚至报错.
默认情况下,左侧菜单不显示层级属性,如果将 showLevel 属性设置为 true 可以显示层级数字.
示例:
![48ab1812c9266c487b829df555cb6dd2.png](https://i-blog.csdnimg.cn/blog_migrate/c43f840c6b275f81c4b01be9aa13bb4f.jpeg)
效果:
![d5027d326809d623170c0dcb369b1861.png](https://i-blog.csdnimg.cn/blog_migrate/d7817782c8545c1ccb8987337660e9bc.jpeg)
gitbook-theme-default-hide-level.png
默认情况下左侧菜单树不显示目录层级
![4d8a08fc7f09b2657e2b440f8427c69e.png](https://i-blog.csdnimg.cn/blog_migrate/bb5629f1832e3d4bf36fcf7b1ea4bba5.jpeg)
gitbook-theme-default-show-level.png
开启层级显示设置后,左侧菜单树显示当前目录层级
theme-comscore 主题
插件地址:
https://plugins.gitbook.com/plugin/theme-comscore
default 默认主题是黑白的,而 comscore 主题是彩色的,即标题和正文颜色有所区分.
示例:
![4add14ac120da6e94dc7a8178ed7ccf9.png](https://i-blog.csdnimg.cn/blog_migrate/4d60afd5045c7a27dff5a2479ae6ae3c.jpeg)
效果:
![2c285ce9c40429d8547375d2d755ab9b.png](https://i-blog.csdnimg.cn/blog_migrate/0625127db0ec72754bab9a34f43f8afb.jpeg)
gitbook-theme-default.png
默认情况下各级标题颜色均是黑色,不同级别的标题仅仅是大小区别.
![64750d103a633369df29dd3c69ba5e54.png](https://i-blog.csdnimg.cn/blog_migrate/582f680419289b9dfe437aafe073384a.jpeg)
gitbook-theme-comscore.png
设置 comscore 主题后,各级标题颜色不同,不仅仅是大小不同.
API 文档
theme-api 插件
插件地址:
https://plugins.gitbook.com/plugin/theme-api
如果文档本身是普普通文档模式,切换成 api 文档模式后并不会有太大变化,除非一开始就是接口文档,那样使用 theme-api 插件才能看出效果.
示例:
![b72890805752daeb687d5b21f5c37d91.png](https://i-blog.csdnimg.cn/blog_migrate/bb8b383409a35a45c275e7dd4b9e8d06.jpeg)
语法:
- 方法区
![3edfbbef228ef6261098f60385f74f10.png](https://i-blog.csdnimg.cn/blog_migrate/5f09b8f83e57e39c0e17d514ebb575b3.jpeg)
- 语法区
![df23e4c2746edba7ccdf1456d646389b.png](https://i-blog.csdnimg.cn/blog_migrate/cdc607446362e525b45721e363d7ee10.jpeg)
示例:
![ba6ce685f95ca873ad88b4b1a75994de.png](https://i-blog.csdnimg.cn/blog_migrate/d849207d80248239a7a7a9ba02230576.jpeg)
效果:
![84cda4f2e38917e2983b6ac6cf5e15d3.gif](https://i-blog.csdnimg.cn/blog_migrate/8d5dcca3169657eec280d522fa385243.gif)
gitbook-theme-api.gif
添加 api 相关方法后的文档效果,正常会两列显示并在右上角增加语言切换工具.
FAQ 文档
theme-faq 插件
插件地址:
https://plugins.gitbook.com/plugin/theme-faq
theme-faq 可以帮助我们构建问答中心,预设好常见问题以及相应答案模式,同时为了方便搜索到问题或答案,一般需要搜索插件的配合.
示例:
![803203af9ac2d0845ee71e8f3c89b1a1.png](https://i-blog.csdnimg.cn/blog_migrate/ad2e49d0bb9ca6821cfad366ed3ecb7a.jpeg)
帮助中心没有工具栏,因此涉及到工具类的插件一律失效或主动移除,同时默认搜索插件也会失效.
语法:
- 增加文章间的关联
![bcd25793dd3b17172e8ab25ea4a9bd69.png](https://i-blog.csdnimg.cn/blog_migrate/471359498b43124886bfad240ce74b43.jpeg)
在当前页面底部显示延伸阅读,支持 yaml 语法关联到其他页面.
- 增加头部 logo
![1eb571e500916ee794009994cab9189b.png](https://i-blog.csdnimg.cn/blog_migrate/72131a8d6c0f0482e3e57f73c5fd413a.jpeg)
新建 _layouts/website/page.html 文件,用于扩展当前主题插件来增加自定义 logo.
- 增加导航栏链接
![4e35e1d64562ade9b726d94f8cb2f669.png](https://i-blog.csdnimg.cn/blog_migrate/20043a4eb05aa296a64aa53a8b92464c.jpeg)
新建 _layouts/website/page.html 文件,用于扩展当前主题插件来增加自定义导航栏链接.
示例:
![a024d8711f6b8d29c36bf226ed584488.png](https://i-blog.csdnimg.cn/blog_migrate/5e3fd6c4e9138b44205acbbfd224eef3.jpeg)
新建 _layouts/website/page.html 文件,增加自定义 logo 和导航栏链接.
效果:
![489885b260938ba7d59de98f9ba1598e.png](https://i-blog.csdnimg.cn/blog_migrate/fd536b1ad8d94446aba5150808deb3d4.jpeg)
gitbook-theme-faq.png
小结
本节主要讲解了常用的三种文档模式,其中 default 主题插件,适合一般的博客类网站或静态网站,api 主题插件适合接口文档的编写,faq 主题插件则适合帮助中心.
三种主题插件分别对应不同的应用场景,默认情况下使用的是 default 主题插件,平时介绍的大多数功能插件也大多适合这种主题,另外两种主题可能就不能很好兼容第三方插件,需要亲身体验.