一、初衷
身为一名学计算机出身的工科背景从业者，在写作上一直钟情于Markdown，截至目前发现最好用的编辑器是Typora，它凭借简洁、流畅的书写体验，让人爱不释手。随着近些年写作需求越来越多，笔者一直希望能够找到一个良好支持Markdown的笔记平台，用以管理自己的输出，因此开始调研一些成熟的产品，先后包括：
以上各笔记的对比分析可参考如下文章
《2020年最好用的云笔记软件推荐》
搜罗完一圈儿后发现，好用的太贵，不花钱的又总是在一些关键方面显得不足，例如：OneNote依赖翻墙、SimpleNote不能放图片等等。
纠结困惑之余，笔者突然想到，难道不能把Typora跟其他的工具结合起来，一同打造一个个人写作平台吗？
带着问题再经过一轮搜索后，最终锁定了Typora+Gitbook+NAS的解决方案。
二、解决方案简介
整个解决方案由三部分内容构成：
-
Typora：编辑工具
Typora是一款十分值得安利的Markdown格式文本编辑器，它凭借实时预览、多平台支持、便捷的素材插入，以及诸多交互细节上的完美考量，较其他编辑器能带来更舒服的书写体验，因此深受众多用户的喜欢。
Typora界面
-
Gitbook：图书构建及发布管理工具
Git是目前世界上公认的最先进的分布式版本控制系统。乍眼一看，好像Gitbook跟Git是类似的工具，但实际上，Gitbook是一个基于Node.js的开源命令行工具，它可以实现对Markdown文档的有序组织和格式转化，即可以将Markdown文档组织成册，也可以将Markdown文档转化为HTML、PDF、eBook等格式。 -
Git/NAS：版本管理工具【可选】
Git就不必多讲。NAS准确来说的话是网络存储器的统称，现在也常常被用作个人云的代名词。如果是个人的话，NAS的存储能力以及版本管理能力就足够满足需要。当然，如果你想把写的文档存储在个人电脑上，并能够很好的手动管理的话，其实Git和NAS都可以不需要。
三、搭建（以Mac为例）
版本信息：
系统版本：MacOS Mojave 10.14.6
Node：v12.16.1
Npm：v6.13.4
Nvm：v0.35.3
GitBook CLI version：v2.3.2
GitBook version：v3.2.3
1、安装Typora
下载地址：https://www.typora.io/
根据系统类型，选择不同的安装包，目前支持Mac、Windows和Linux三个平台。
2、安装Gitbook
- 安装Node.js
如果系统已经安装brew，可以通过以下方式安装Nodejs
$ brew install node
也可以前往官网下载安装包
https://nodejs.org/en/
Nodejs下载
Node.js安装成功后，在命令行可通过以下方式查询到版本信息：
$ node -v #查询node版本
v12.16.1 #显示结果
$ npm -v #查询npm版本
6.13.4 #显示结果
- 安装Nvm
Nvm是Mac系统下比较推荐的Node版本管理工具，用于切换Node的不同版本。
$ brew install nvm
安装成功后，可以通过如下方式查看目前Node的版本配置信息：
$ nvm ls #查询node配置情况
-> system
iojs -> N/A (default)
node -> stable (-> N/A) (default)
unstable -> N/A (default)
- 切换Node版本
基于高版本的Node安装Gitbook v3.2.3，会在创建的文档实例转换成HTML后，出现目录无法点击跳转的情况，解决的办法就是将Node降级到v6.16.0版本后再安装Gitbook。
$ nvm install 6.16.0
$ nvm use 6.16.0
$ nvm ls
v6.16.0
-> system
node -> stable (-> v6.16.0) (default)
stable -> 6.16 (-> v6.16.0) (default)
iojs -> N/A (default)
unstable -> N/A (default)
lts/ * -> lts/erbium (-> N/A)
lts/argon -> v4.9.1 (-> N/A)
lts/boron -> v6.17.1 (-> N/A)
lts/carbon -> v8.17.0 (-> N/A)
lts/dubnium -> v10.19.0 (-> N/A)
lts/erbium -> v12.16.1 (-> N/A)
- 安装Gitbook
当Node版本切换完成后，执行如下命令安装Gitbook
$ sudo npm install -g gitbook-cli
/usr/local/bin/gitbook -> /usr/local/lib/node_modules/gitbook-cli/bin/gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 11.621s
$ gitbook init
Installing GitBook 3.2.3
...
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
至此，如果没有出现问题的话，那么整个搭建过程算是顺利完成。接下来就可以体验以下如何利用Gitbook来管理Markdown文档了。
四、使用
下面就以一个小例子，演示一下如何通过Typora和Gitbook来创建你的文档。
1、创建文档目录并初始化
我们按照如下指令，在桌面新建一个测试目录TestBook，进入该目录后，通过Gitbook初始化得到README和SUMMARY两个基础文件。这样，TestBook就变成了一个文档集，或更直白点说，它就是一本书。README像是书的序言，而SUMMARY则是书的目录。
$ cd ~/Desktop/
$ mkdir TestBook
$ cd TestBook
$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
2、编辑文档大纲并重新构建
用Typora打开TestBook，可以看到如下内容
TestBook
按照如下内容编辑TestBook的文档大纲
# Summary
* [什么是5W2H](README.md)
* [Part I：5W](part1/README.md)
* [What](part1/what.md)
* [Why](part1/why.md)
* [Who](part1/who.md)
* [When](part1/when.md)
* [Where](part1/where.md)
* [Part II：2H](part2/README.md)
* [How](part2/how.md)
* [How much](part2/howmuch.md)
然后再使用Gitbook对TestBook进行初始化，生成大纲列出的各个md文件和子目录
$ gitbook init
info: create part1/README.md
info: create part1/what.md
info: create part1/why.md
info: create part1/who.md
info: create part1/when.md
info: create part1/where.md
info: create part2/README.md
info: create part2/how.md
info: create part2/howmuch.md
info: create SUMMARY.md
info: initialization is finished
构建完成后，发现TestBook下的目录结构是这样的
TestBook
├── README.md
├── SUMMARY.md
├── part1/
| ├── README.md
| ├── what.md
| ├──why.md
| ├──who.md
| ├──when.md
| └── where.md
└── part2/
├── README.md
├── how.md
└── howmuch.md
3、启动服务通过浏览器查看文档
对文档目录下的md文件分别进行编辑后，可执行如下命令生成html格式的文档并查看
# 构建过程
$ gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 10 pages
info: found 0 asset files
info: >> generation finished with success in 0.6s !
# 服务启动过程
$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...
info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 10 pages
info: found 0 asset files
info: >> generation finished with success in 0.6s !
Starting server ...
Serving book on http://localhost:4000
最后，打开浏览器，输入http://localhost:4000便可以访问文档了。
在线查看文档
网友评论