文档编写之从Jupyter notebook到Gitbook迁移之路 写作神器了解一下

前言

做一个程序员，写文章是必不可少的，比如记一记平时的心得，异常集锦，学习某个知识点的经历，技术总结，开发教程等，那一个很明显的问题就出来了，用什么工具写呢？

在最开始做程序员的时候，有用记事本写，可是那排版样式太简陋了，只能写文字，渐渐的淘汰掉；后来用office全家桶写，写着写着发现这工具用来写我们这东西有点太臃肿了（二八定律：80%的时间里我们只会只用20%的功能），写作速度慢，排版复杂，对代码的支持有限

到后来在使用Github的过程中，发现使用Markdown语法写文档原来能这么6，排版也很好看，对代码的支持也很好，而且很多开发工具都支持Markdown语法了，但是每次要写文章的时候都把开发工具打开或者打开github，显然这很不简洁，也不专业

直到有一天，我开始学Python了，接触到一个叫Jupyter notebook的工具，我擦，我发现这玩意是个神器；在这个工具里不仅能写代码，还能同时写文章，做到一个页面同时记笔记和写代码的能力，也是支持Markdown语法，还能将成果实时分享给别人；还能将文件转成html，md，pdf等格式文件

写着写着发现还是有点不足的，一个是写出来的东西没有整体的章节目录，没有像阅读书籍似的感觉；另一个是Jupyter本质上是一个Web程序，有时候你不需要写代码，就只想写文章，写笔记，这时候用它就显得有点笨重了

直到有一天接触到了Gitbook，我发现终于找对了我要的那个东西，兼容性好，易于版本控制、可以实时分享预览、支持多人协作、更有专业感

其实Jupyter notebook和Gitbook都是两款非常优秀的工具，然而是两个不同功能的工具；Jupyter notebook主要是用在数据科学和机器学习方面的，写文章只是它一个小功能；而Gitbook就更专业化，对文章写作的支持更好；这么优秀的工具一定要分享给大家，通过这篇文章来记录下它们的使用（ 不光技术人员使用，其它岗位同样也可以）

GitBook做出来的文档在浏览器预览如下图，由于众多插件的支持，页面预览拥有很多功能，比如搜索，分享，评论等；同时非常适合做一个个人网站

---

Markdown

什么是Markdown

Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式

这是一种有着14年历史的由作家Aaron Swartz 和程序员John Gruber创建的文本编辑语言，尽管已经有十多年的历史了，Markdown似乎正在进入一个黄金时代，在新的地方出现并以新的方式使用。你甚至有可能在没有意识到的情况下在Markdown友好的编辑器中写过

Markdown的语法简洁明了、上手快，而且功能比纯文本更强，文件后缀是 .md；在数据科学领域，Markdown已经广泛使用，极大地推进了动态可重复性研究的历史进程

市面上支持Markdown语法的编辑器非常多，比如Typora、MacDown、Bear、MarkdownPad、MarkdownX、AndroidStudio、Intellij Idea、RStudio、PyCharm、Atom、Github、简书、CSDN 以及 GitBook 自家的 GitBook Editor 等等

关于Markdown语法这里就不做叙述了，可参考Markdown语法

---

Jupyter notebook

对于机器学习和数据科学的工作者来说，如果都应该使用或必须使用一种工具，那毫无疑问，它就是Jupyter Notebook（Jupyter命名是取自Julia语言，Python语言，R语言，曾用名iPython Notebook）；数据科学家可以在上面创建和共享自己的文档，从实现代码到全面报告，Jupyter Notebook大大简化了开发者的工作流程，帮助他们实现更高的生产力和更简单的多人协作。也正是因为如此，它一直以来都是数据科学家们最喜欢的工具之一

第一个问题：Jupyter notebook是什么？

Jupyter Notebook 是一个开源的 Web 应用程序，便于创建和共享文学化程序文档，支持40多种编程语言，支持实时代码、数学方程、可视化和 Markdown，其用途包括数据清理和转换、数值模拟、统计建模、机器学习等等。目前，数据挖掘领域中最热门的比赛 Kaggle 里的资料都是 Jupyter 格式

Jupyter notebook 源自 Fernando Perez 发起的 IPython 项目。IPython 是一种交互式 shell，与普通的 Python shell 相似，但具有一些很好的功能（例如语法高亮显示和代码补全）。notebook 的工作方式是：你通过浏览器连接到该服务器，而 notebook 呈现为 Web 应用。你在 Web 应用中编写的代码（你在浏览器中看到的 notebook）通过该服务器发送给内核 IPython 内核（在后台运行的 IPython 应用程序），内核运行代码，并将结果发送回该服务器。之后，任何输出都会返回到浏览器中。保存 notebook 时，它将作为 JSON 文件（文件扩展名为 .ipynb）写入到该服务器中

它提供了一个环境，你可以在其中记录代码，运行代码，查看结果，可视化数据并在查看输出结果。这些特性使其成为一款执行端到端数据科学工作流程的便捷工具 ，可以用于数据清理，统计建模，构建和训练机器学习模型，可视化数据以及许多其他用途，如图

如上图便展示了一个 .ipynb 文件的示例页面。其中一对 In Out 会话被视作一个单元，称为 cell。第一个 cell 里我写入的内容其实是：

```
##LaTex 演示
---
$Z=\frac{X-\bar{X}}{S}$
```
除了内嵌 matplotlib 绘图外，Notebook 还同时提供了对 LaTex 和 MarkDown 的支持

它具有以下优势：

• 可选择语言：支持超过40种编程语言，包括Python、R、Julia、Scala等。
• 分享笔记本：可以使用电子邮件、Dropbox、GitHub和Jupyter Notebook Viewer与他人共享。
• 交互式输出：代码可以生成丰富的交互式输出，包括HTML、图像、视频、LaTeX等等。
• 大数据整合：通过Python、R、Scala编程语言使用Apache Spark等大数据框架工具。支持使用pandas、scikit-learn、ggplot2、TensorFlow来探索同一份数据。

第二个问题：怎么安装？

Jupyter Notebook原来也叫iPython Notebook，顾名思义，它和Python关系紧密

官方在文档中强烈建议新用户用Anaconda打包安装Python和Anaconda——所谓懒人方法，小白必备。其实除了提到的两个工具，Anaconda还包含数据科学和机器学习中经常需要用到的各种软件包，只需下载、解压、安装，所有工具就都一步到位了，可以参考博主的Python3.6之Windows下Anaconda3和PyCharm 开发环境安装

第三个问题：如何启动Jupyter Notebook？

打开cmd，输入jupyter notebook，敲回车就可以打开了，会在浏览器中打开一个页面，网址一般为网址为http:// localhost:8888/tree，页面如图

第四个问题：如何使用？

关于使用它来编写md文件，这里就不做多介绍了，熟悉Markdown语法就行了，这里介绍下它其它方面的能力

当笔记本打开后，它的顶部有Files、Running和Clusters三个选项。其中Files中列出了所有文件，Running显示了你已经打开的终端和执行过的笔记本，Clusters则是IPython parallel提供的

如果你想新建一个笔记本，单击面板右侧的“New”，它会跳出4个选项：

• Python 3
• Text File：你会得到一个空白的页面。它相当于一个文本编辑器，你可以在上面输入任何字母、单词和数字，所以选择好编程语言后，你是可以在上面写脚本的。此外，它还提供查找和替换文件中的单词的功能，如图（支持非常多的语言）
  
• Folder：创建一个新的文件夹
• Terminal：和Mac、Linux计算机上的Terminal一样，都是在Web浏览器中创建终端支持。只需在终端输入Python，一个Python脚本就写好了

我们重点介绍下第一个选项，创建一个Python 3文件，文件样式如图：

其中带图标的一排按钮依次表示保存、添加、剪切、复制、粘贴、向上移动cell、向下移动cell、运行代码、停止运行和撤销；在撤销按钮旁边有一个下拉框，如图：

选项意义如下：

• Code：这个顾名思义，就是写代码的类型
• Markdown：非常常见的轻量级标记语言，用来为代码添加注释或写笔记文章
• Raw NBConvert：一个命令行工具，可以把你的笔记本转换成另一种格式，如HTML
• Heading：添加标题，使你的文档看起来更干净整洁，它现在已经变成Markdown里的一个语法，用#表示

我们可以通过按大写的M和C键在Code和Markdown类型间切换，如图

这里有三行，在notebook中，每一行称为一个cell，即一个单元格，它可以作为一个类似“段落”的概念来进行编辑，不管是执行前还是执行后，而且既可以针对内容进行编辑，也可以对 cell 整体应用 copy、paste、cut 等操作，甚至还可以前后移动 cell 的位置；第一行是Markdown类型，后面两个是Code类型，可以直接编写代码

如果设置为Code类型, 里面的内容就是可以运行的; Heading类型的cell可以帮助我们设置标题(一级,二级,三级等标题), Markdown类型的cell我们可以使用markdown的语法来编辑文本

Jupyter Notebook的魔术命令：Magic关键词

作为iPython的继承者，开发人员已经在Jupyter Notebook中加入预定义的魔术命令（magic function）。这是一种增加便捷性和互动性的工具，如果要查看命令列表，你可以输入（注：通常不需要“%”）：%lsmagic，然后执行就可以看到一串内容，如图

• Magic 关键字是可以在单元格中运行的特殊命令，能让你控制 notebook 本身或执行系统调用（例如更改目录）
• Magic 命令的前面带有一个或两个百分号（% 或 %%），分别对应Line-wise（行 Magic 命令）和Cell-wise（单元格 Magic 命令）。行 Magic 命令仅应用于编写 Magic 命令时所在的行，而单元格 Magic 命令应用于整个单元格

注意：这些 Magic 关键字是特定于普通 Python 内核的关键字。如果使用其他内核，这些关键字很有可能无效

---

GitBook

正因为Jupyter Notebook功能太丰富了，如果只拿来写文档那就太浪费，除非你是做数据科学的；这时候一个更专业化的文档制作工具来了，它就是GitBook

第一个问题：GitBook是什么

GitBook主页
Github主页
GitBook Documentation

咋一看这名字，你可能以为它是跟git有什么关系，或者是一本关于git的书，其实它跟git没有一毛钱关系，就跟雷锋和雷峰塔一样，根本是两码事

GitBook本质上是一个基于Node.js的命令行工具，支持 Markdown 和 AsciiDoc 两种语法格式；通过它我们可以快速生成书籍目录文件，得到HTML、PDF、eBook 等格式的电子书；平时看到各种个人技术网站基本上都是通过GitBook和Git实现的

贴一段官网介绍

GitBook既是一个用于编写和托管文档的在线平台，也是一个开源书籍格式和工具链。
成千上万的用户使用GitBook编写文档（库，API，工具等）或知识库（如F.A.Q.）。 人们还使用GitBook发布技术书籍，教材和许多其他内容

所以GitBook不是Markdown编辑工具，也不是像Git那样的版本管理工具；但是如果我们只用Gitbook，那你绝对没有掌握它的正确用法；如果你将Gitbook和Git及Markdown编辑工具结合起来用，这就能发挥Gitbook的最大威力，让你体验飞一般的写作感觉；然后使用 GitBook 查看管理文档，制作电子书，预览展示内容；同时通过 Git 管理书籍内容的变更，并将其托管到云端（比如 GitHub、GitLab、码云，或者是自己搭建的 Git 服务器），实现多人协作

GitBook+Markdown编辑工具+Git组合使用的优势：

• 文档编写成本低，速度快，Markdown语法简单，花几分钟了解后你就能开始写文档了
• 易于扩展，可以与其它格式转换，比如需要复杂排版时，还是需要依靠word，但是我们可以通过GitBook工具将Markdown文件转成Word 格式，再继续编写
• 方便多人协作，比如编写接口文档或者方案，可能需要团队中整个项目的人员参与编写，这就涉及到多人协作了，然而git可以搞定这一切
• 将更多时间用于内容编写，而不是像office家族，需要花很多时间在学习工具使用上

第二个问题；怎么安装

因为Gitbook是基于Node.js的，所以需要先安装它再进行后续操作

Node.js下载地址

下载下来后一直点next就安装完成了，查看是否安装成功，可以打开cmd，输入npm -v命令：如图

看到版本号说明安装成功了

注意：有人好奇npm是啥，其实它是一个用于管理基于node.js编写的package的命令行工具，安装node的时候默认会安装npm，不需要单独安装

接下来就是安装Gitbook了，输入命令npm install gitbook-cli -g

其中gitbook-cli是Gitbook的一个命令行工具，通过它可以在电脑上安装和管理gitbook的多个版本，要注意它和gitbook是两个工具

安装完成后就可以使用gitbook命令了，可以输入gitbook -V 查看安装的gitbook和gitbook-cli版本；gitbook-cli 会将下载的 gitbook 的不同版本放到 ~/.gitbook中

注意：有可能因为网络问题会导致下载失败，所以需要提前设置代理，命令如下

npm config set proxy http://server:port

第三个问题：怎么使用

先看下常规的gitbook命令

gitbook命令

• gitbook help：列出gitbook的帮助信息
• gitbook --help：列出gitbook-cli的帮助信息
• gitbook ls：列出本地所有的gitbook版本
• gitbook ls-remote：列出远程可用的gitbook版本
• gitbook fetch 3.2.3：安装对应的gitbook版本（这里是3.2.3版本）
• gitbook update：更新到gitbook的最新版本
• gitbook install：安装插件，只需要将所需要的插件添加到book.json中，再执行该命令就可以安装
• gitbook uninstall 3.2.3：卸载对应的gitbook版本（这里是3.2.3版本）
• gitbook builid --debug：输出错误信息
• gitbook init：设置和创建章节文件
• gitbook build：构建书籍并生成静态网页
• gitbook serve：生成静态网页并运行服务器，包含git build了
• gitbook build --gitbook=3.2.3：生成时指定gitbook的版本（这里是3.2.3版本）, 本地没有会先下载

typora

这里推荐的Markdown编辑工具是typora，跨平台且免费，功能强大，当然了你也可以选择其它工具，只要支持Markdown就行了

Typora Windows是一款简单免费的Markdown文本编辑器，具备好用、高颜值、轻量、免费等特色，可以使表格编辑变得如此简单，插入图片也变得简单，支持显示目录大纲，还有最好用的代码和数学公式输入，可以为用户提供非凡的汉字输入体验

官方地址：可以去官网下载，但是蛋疼的一点就是有墙，如果需要的话可以联系我

Typora语法：关于Typora语法相关的可以参考

安装打开后编写内容后如图

会Markdown语法就能熟练使用了，不难；要注意的一点是，虽然Typora输出格式多样，但是Typora 的文件导入/导出功能使用 Pandoc 把 Markdown 源码转换成不同的文件格式，所以我们如果想使用文件导入/导出功能，必须先安装 Pandoc

Pandoc官网

同样有墙的存在，可能访问不了，需要的话可以联系我

Git

至于Git的使用这里就不叙述了，可以参考博主的Git命令的使用记录及出现的错误解决方式

---

组合使用

第一步：创建文档概要信息

假如现在你准备写一本叫深入理解Java虚拟机的书，那么就先建立一个深入理解Java虚拟机的文件夹，首先我们在该目录下执行gitbook init 命令，这样该目录下就会多出两个文件，如图

• README.md：用来写一些描述信息，比如作者的相关信息，书籍的相关信息等

• SUMMARY.md：看Summary的单词意思就知道是概要信息，主要存放 GitBook 的文件目录结构信息，左侧的目录就是根据这个文件来生成的；可以在 book.json 重新定义该文件的对应值；它通过 Markdown 中的列表语法来生成章节目录文件的父子关系，下面是一个简单的示例：

  # 目录
  
  * [前言](README.md)
  * [个人简介](ABOUTME.md)
  * [关于博客](ABOUTBLOG.md)
  * [第1章 走近Java](第1章/README.md)
      * [1.1. 概述](第1章/1.1. 概述.md)
      * [1.2. Java技术体系](第1章/1.2. Java技术体系.md)
      * [1.3. Java发展历史](第1章/1.3. Java发展历史)
  * [第2章 Java内存管理](第2章/README.md)
      * [2.1. 概述](第2章/2.1. 概述.md)
      * [2.2. Java虚拟机栈](第2章/2.2. Java虚拟机栈.md)
  * [第3章 垃圾收集器和内存分配策略](第3章/README.md)
      * [3.1. 概述](第3章/3.1. 概述.md)
      * [3.2. 引用计数算法](第3章/3.2. 引用计数算法.md)
      * [3.3. 标记-清除算法](第3章/3.3. 标记-清除算法.md)
  

  所用到的语法格式就是 ：[提示语] (链接)，如图：
  
  在README.md中写一写简介

  # 前言
  
  ​​	这是一本带你入坑的Java书籍
  

默认只有上面两个文件，但是后续可能会有book.json和GLOSSARY.md等两个文件，同时在生成电子书的时候还会生成大量的nodejs文件以及_gitbook的电子书文件，所以建议配置.gitignore文件，其中

• book.json：是gitbook的配置文件，包括插件的配置文件，通过插件可以丰富电子书的功能，可参考配置2

• GLOSSARY.md：词汇表文件，该文件主要存储词汇信息，如果在其他页面中出现了该文件中的词汇，鼠标放到那个词汇上会给出词汇示意
  Glossary 文件的格式如下所示：

  ## Git
  分散式版本控制软件
  
  ## Markdown
  Aaron Swartz 跟John Gruber共同设计的排版语言
  

  其中Git和Markdown是其它文件出现的词汇

• .gitignore：通过Git工具进行版本管理时的文件，将不纳入版本控制的文件添加到该文件里；不过在windows系统上默认是不允许用户直接创建点号开头的文件，因为点号开头的都是隐藏文件；不像Linux可以直接创建；所以需要借用Git Bash创建，因为Git bash用的是linux下的命令（不要使用cmd，cmd用的是Windows自己的命令），输入touch .gitignore就可以生成了

第二步：生成章节目录文件

这里再次执行gitbook init命令，GitBook会查找SUMMARY.md 文件中描述的目录和文件，如果没有则会根据目录层级关系将其创建，如图：

如果不使用Gitbook工具，光使用Typora，就蛋疼了；不想创建文件就把所有内容写在一个md文件里，显然内容会变得繁杂，不利于阅读和后续维护；要创建文件的话，这么多文件看着就累

这些创建好后就是你的写作时间了

第三步：生成电子书

在生成电子书之前我们可以建立book.json文件进行一些配置，配置清单如下：

	{
	  "title": "字符集与字符编码",
	  "description": "字符集与字符编码",
	  "author" : "mango",
	  "language" : "zh-hans",
	  "gitbook" : "3.2.3",
	  "links": {
	    "sidebar": {
	      "GitBook": "https://legacy.gitbook.com/",
	      "GitHub": "https://github.com/GitbookIO/gitbook"
	    },
	    "gitbook": true
	  },
	  "plugins": [
	    "popup",
	    "copy-code-button",
	    "splitter",
	    "-search",
	    "search-pro",
	    "fontsettings",
	    "github",
	    "insert-logo",
	    "-sharing",
	    "sharing-plus",
	    "tbfed-pagefooter",
	    "hide-element",
	    "ancre-navigation",
	    "donate"
	  ],
	  "styles": {
	    "website": "styles/website.css"
	  },
	  "pluginsConfig": {
	    "fontsettings": {
	      "theme": "sepia",
	      "family": "sans",
	      "size": 12
	    },
	    "github": {
	      "url": "https://github.com/Mangosir"
	    },
	    "insert-logo": {
	      "url": "../image/logo.png",
	      "style": "background: none; max-height: 50px; min-height: 50px"
	    },
	    "sharing": {
	      "whatsapp": true,
	      "qzone": true,
	      "twitter": true,
	      "weibo": true,
	      "all": [
	        "douban",
	        "facebook",
	        "google",
	        "hatenaBookmark",
	        "instapaper",
	        "linkedin",
	        "twitter",
	        "weibo",
	        "messenger",
	        "qq",
	        "qzone",
	        "viber",
	        "vk",
	        "pocket",
	        "stumbleupon",
	        "whatsapp"
	      ]
	    },
	    "tbfed-pagefooter": {
	      "copyright": "Copyright © Mango",
	      "modify_label": "该文件修订时间：",
	      "modify_format": "YYYY-MM-DD HH:mm:ss"
	    },
	    "hide-element": {
	      "elements": [".gitbook-link"]
	    },
	    "donate": {
	      "wechat": "微信支付二维码URL",
	      "alipay": "支付宝二维码URL",
	      "title": "",
	      "button": "打赏",
	      "alipayText": "支付宝打赏",
	      "wechatText": "微信打赏"
	    }
	  }
	}

接下来我们就可以构建书籍了，执行 gitbook build 命令构建书籍，默认将生成的静态html文件输出到 _book 目录，如图

build 命令也可以指定路径：

gitbook build [书籍路径] [输出路径]

第四步：预览书籍

电子书生成后，怎么看呢？总不能还在Typora上看吧，虽然也能看，但是预览效果有限，而且有些效果达不到（比如在页面上搜索）；通过一些插件的配合，在浏览器中预览书籍的效果会非常好，不仅仅是自己看，比如你想在会议室或者展厅给别人演示，那在浏览器中展现一定是比在软件里要棒

执行gitbook serve命令，会在本地运行一个服务器，通过http://localhost:4000/可以预览书籍（你也可以直接放在自己的Web服务中查看）

serve 命令也可以指定端口

gitbook serve --port 2333

最终效果如图

其它命令

• 生成 PDF 格式的电子书

  gitbook pdf mybook.pdf
  

• 生成 epub 格式的电子书

  gitbook epub mybook.epub
  

• 生成 mobi 格式的电子书

  gitbook mobi mybook.mobi
  

如果生成不了，你可能还需要安装一些工具，比如 ebook-convert（需要安装 Calibre），可以参考导出PDF；或者在 Typora 中安装 Pandoc 进行导出

第五步：托管Github

如果一个文档需要多人协作的话，就需要通过Git+Github来进行版本管理了，将文档托管到Github上，大家一起完成，至于怎么托管到Github，这里就不叙述了，可以参考博主的上面给出的关于Git使用的文章

你觉得怎么样呢