相信很多童鞋在日常开发中都会有「说明文档」、「学习笔记」和「个人博客」的需求,那么最经济简洁的方式莫过于 GitBook
方案了,10
分钟学习,永久使用。
本文将简单介绍 GitBook
的使用方式以及最佳插件搭配方案,快来运行一个与众不同而且免费托管的个人站点吧!
一、安装与使用
1.安装 GitBook
插件
1 | npm install gitbook-cli -g |
2.查看安装版本
1 | gitbook -V |
控制台会输出如下信息:
1 | # Jartto |
3.初始化
1 | # 建立项目: |
此时,jartto-gitbook-demo
目录下会自动生成如下文件:
1 | . |
4.启动
1 | gitbook serve |
5.访问站点:http://localhost:4000
恭喜你,到这一步我们已经完成了基本版本。
更详细的操作,请查看如下文档:
二、重点说明
1.目录结构
当我们运行 gitbook serve
后,jartto-gitbook-demo
目录下会生成一个 _book
文件夹:
1 | . |
2.关于 README.md
1 | # Introduction |
说明文档,大家应该都不陌生,就不赘述了。
3.关于 SUMMARY.md
1 | # Summary |
SUMMARY.md
其实就是书的章节目录,我们不妨稍作修改:
1 | # Jartto-GitBook-Demo |
效果如下:
三、补充文档
当然,GitBook
的远比我们想象的强大,我们还可以通过 gitbook help
来查看:
1 | build [book] [output] build a book |
四、有趣插件
了解上面的操作,使用 GitBook
已经没有任何障碍了。
如果你还想做一些个性化的操作,不妨继续深入。
要安装插架,需要我们有配置文件 book.json
,我们可以在根目录下创建:
1 | touch book.json |
写入基本配置:
1 | { |
插件安装通用命令:
1 | npm install gitbook-plugin-[插件名] |
例如:我们要安装 flexible-alerts
信息框插件:
1 | npm install gitbook-plugin-flexible-alerts |
效果如下:
还有很多可用插件,具体如下:
- 信息框(
flexible-alerts
) - 阅读统计(
pageview-count
) - 侧边栏宽度可调节(
splitter
) - 页脚版权(
page-copyright
) - 打赏功能(
donate
) - 分享当前页面(
sharing-plus
) - 修改标题栏图标(
custom-favicon
) - 复选框(
todo
) - 显示图片名称(
image-captions
) - 目录折叠(
toggle-chapters
) - 分章节展示(
multipart
) - 插入
Logo
(insert-logo
) Google
分析(ga
)- 返回顶部(
back-to-top-button
) - 代码添加行号和复制按钮(
code
) - 高级搜索,支持中文(
search-pro
) - 添加
Github
图标(github
)
…
需要注意的是:GitBook
默认带有 5
个插件:
highlight
search
sharing
fontsettings
livereload
如果要去除自带的插件,可以在插件名称前面加 -
,例如:
1 | "plugins":[ |
小技巧:NPM
中搜索关键字 GitBook-Plugin
,发现更多插件。
五、效果展示
1.GitBook
扩展:
2.示例一:
3.示例二:
4.示例三:
六、总结
上文介绍了 GitBook
的基本使用和一些实用插件,构建在线文档变得轻而易举。加上 Github
免费的托管平台,我们就可以干更多有趣的事情了。快输出你的 HTML
、PDF
、eBook
技术文档吧~