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

【工具及零碎知识】 专栏收录该内容
9 篇文章 0 订阅

前言

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

在最开始做程序员的时候,有用记事本写,可是那排版样式太简陋了,只能写文字,渐渐的淘汰掉;后来用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 &copy 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使用的文章

你觉得怎么样呢

  • 2
    点赞
  • 0
    评论
  • 10
    收藏
  • 一键三连
    一键三连
  • 扫一扫,分享海报

©️2021 CSDN 皮肤主题: 数字20 设计师:CSDN官方博客 返回首页
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值