一、初衷

身为一名学计算机出身的工科背景从业者，在写作上一直钟情于Markdown，截至目前发现最好用的编辑器是Typora，它凭借简洁、流畅的书写体验，让人爱不释手。随着近些年写作需求越来越多，笔者一直希望能够找到一个良好支持Markdown的笔记平台，用以管理自己的输出，因此开始调研一些成熟的产品，先后包括：

• 印象笔记
• OneNote
• Notion
• SimpleNote
• 有道云笔记
• 为知笔记
• 蚂蚁笔记

以上各笔记的对比分析可参考如下文章
《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 -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便可以访问文档了。

在线查看文档