GitBook

更新日期: 2016-05-07 阅读次数: 23435 分类: 自建博客

为何又切换到了 GitBook

大象笔记最初是使用 VimWiki,但是语法上与 Markdown 有差异。之后转投 Pelican,但是越来越觉得更像是一个记录流水的 Blog,而不像是一个 Wiki。没有记录的乐趣。

直到遇到 GitBook。

首先,GitBook 的客户端异常人性化,因为是为写书而生,所以文档层级非常直观,类似 VimWiki,解决了 Pelican 的核心短板。GitBook 客户端也解决了使用 Vim 写 Markdown 没有实时预览的问题。纯文本实际上有没有预览是没有区别的,但是如果插入了图片,没有预览的话,就相当于内容缺失。

GitBook 在生成 Web Site 的时候,也相对便捷许多。各种三方组件,集成进来非常简单。本地调试也不需要自己搭建 web server,用自带的 gitbook serve 即可。

产品、程序文档用 GitBook 来写就更合适不过了。因为会涉及到大量的主题,写在单页 Markdown 中是不合适的,而用 GitBook 编辑之后,再生成 PDF 就方便许多。协作更新,放到团队 Git 仓库即可。

初始化

参考 GitHub

安装 gitbook

npm install gitbook-cli -g

初始化,自动生成 gitbook 配置文件

gitbook init

本地调试

gitbook serve

服务器上生成静态文件

gitbook build

个性化配置

book.json

中文用户去掉单词拼写检查

由于 GitBook 不支持中文字典,所以书写中文时,会不断提示单词拼写错误。关闭方法:

File -> Preferences -> Proofreader

uncheck spellchecking & proofreading

如何在手机上随时随地记录

Working Copy 是手机上一个 Git 客户端,可以随时编辑。

编辑器

官网自带的 GitBook 并不是一个好的编辑器,至少在 5.0.5 版本,在 Ubuntu 上使用,各种 bug。例如

  • 配置修改无故丢失。禁止中文语法检查经常性失效。
  • 编辑内容无故丢失。摸不着头绪。

非常打击写 Wiki 的积极性。痛定思痛,决定还是使用老伙计 VIM。编辑起来也非常方便

  • 首先用 VIM 打开 SUMMARY.md 文件,用于浏览/查找要编辑的文件名。
  • 新开 TAB 用于编辑对应的 markdown 文件。
  • 使用 git 手动提交,规避 GitBook 无意义的提交记录。

关于作者 🌱

我是来自山东烟台的一名开发者,有敢兴趣的话题,或者软件开发需求,欢迎加微信 zhongwei 聊聊, 查看更多联系方式