第六章 Markdown工具一箩筐

6.1 记笔记

  笔记软件主要是用来帮助用户记录重要信息、事件及想法的。在笔记软件中使用Markdown写作的优点显而易见——除了能够使用笔记软件自身的所有功能，还能享受Markdown专注而高效的写作特点。目前市场上比较流行的笔记软件主要有印象笔记、有道云笔记和OneNote等。

6.1.1 印象笔记

  印象笔记也支持Markdown了，它支持基础Markdown语法和GFM语法，并且跟有道笔记一样，能够通过使用模板快速绘制数学公式、流程图、时序图、甘特图，令人惊喜的是，印象笔记还提供了快速绘制多种图表的功能。
  总之，一句话，在印象笔记中使用Markdown写作，让人有一种愉悦的感觉，从功能到配色，到处透露着“高级感”。
  在印象笔记的左上角单击【新建Markdown笔记】可以新建Markdown笔记，也可以使用快捷键新建。

  默认使用的是经典的Markdown编辑模式，左边是源码，右边是预览。通过工具栏上的【切换编辑模式】按钮能够在纯编辑模式和经典模式之间切换，通过右上角的【Markdown预览】按钮能够进入纯预览界面。
  在印象笔记的工具栏上，提供了常用标记的快速插入功能，包括一些常用的图表模板，把鼠标放到图标上，会显示图标的功能提示。

• 使用印象笔记中的Markdown添加流程图和图表的便捷之处：

1. 添加流程图
   在单击工具栏上的【添加流程图】之后，会在源码编辑器中插入流程图的代码模板，我们只需要根据这个模板进行修改就可以了，不必再从头写起（何况语法并不容易记住）。

2. 添加图表
   印象笔记支持在Markdown中添加4种图表——饼图、折线图、柱状图、条形图，不同图表之间可以通过改变源码中type的值进行切换，可选值为pie、line、column、bar。令人惊喜的是，这些图表在预览界面都是可以进行交互操作的。

3. 添加图片
   在印象笔记中可以通过工具栏上的【插入图片】上传本地的图片，也可以直接拖拽添加，或者从剪切板中粘贴，而这些功能在有道云笔记中只有会员才可以使用。
   另外，我们还可以非常方便地设置图片大小：

   1. 本地图片/网络图片@w=100。
   2. 本地图片/网络图片@h=100。
   3. 本地图片/网络图片@w=100h=100。

4. 文件转换
   在编辑界面或源码界面上，单击鼠标右键，可以导出Markdown格式的笔记，也可以将笔记转换为PDF格式的文件。

  通过印象笔记转换的PDF文件非常漂亮，它基本保持了Markdown预览时的效果。另外，我们还可以在印象笔记中对PDF文件进行标注、预览和下载。

6.1.2 有道云笔记

  有道云笔记应该是国内使用用户最多的笔记软件了，它功能全、速度快，而且免费（针对大部分功能）。它对Markdown的支持也比较全面，支持在电脑端、手机端、Web端等多平台使用Markdown，除支持基础的Markdown语法外，有道云笔记还支持代码高亮、任务列表、表格、数学公式，能够高效绘制流程图、序列图、甘特图。
  在电脑端和Web端，都是通过在文件夹处单击鼠标右键→【新文档】→【新建Markdown】来新建Markdown文件的。
  在手机端，则通过单击【+】按钮，选择【Markdown】来新建笔记。
  创建Markdown文件之后，就进入我们熟悉的Markdown编辑环境了，相信你已经对Markdown语法驾轻就熟了。如果懒得去记这些语法，在工具栏上提供有一排快速插入语法的图标，一目了然。
  值得注意的是，PC端的有道云笔记提供了快速插入公式和图表的模板，我们只需要根据模板进行修改就可以得到自己想要的图表了，

小提示：

1. 在有道云笔记中，只有会员才能在Markdown中直接上传本地图片，这一点很不方便，而印象笔记没有这个限制。
2. 在有道云笔记中，Markdown预览界面可以直接进行演示，但在印象笔记中必须是会员才可以。

6.1.3 OneNote

  OneNote本身并不直接支持Markdown，但如果想在OneNote中使用Markdown，可以通过插件来实现。
  插件下载地址：https://www.onenotegem.com/one-markdown.html，目前只支持Windows版本。

6.2 在线多人协作工具

  在线文档可以让我们随时随地创建、编辑、与他人协作处理文档，是协同办公必备的工具。目前比较流行的两个在线协作工具是腾讯文档和石墨文档，它们都支持一些简单的Markdown语法。在使用时你可能找不到切换Markdown的入口，这是因为根本没有入口，直接通过“标记符号+空格”使用就好了，效果是实时渲染的。

6.2.1 腾讯文档

  腾讯文档支持的Markdown语法有标题（6级）、分隔线、有序列表和无序列表。

6.2.2 石墨文档

石墨文档支持的Markdown语法：

1. 标题（3级）。
2. 有序列表。
3. 无序列表。
4. 任务列表（[]+空格）。
5. 代码块（行首输入```+空格）。

  除在编辑时可以使用上述简单的Markdown语法外，石墨文档还支持导入/导出Markdown文件，能正常解析几乎所有GFM语法。

6.3 写博客

6.3.1 知乎

  知乎并没有专门的Markdown编辑器，但在发布文章或回答问题时，可以使用粗体、斜体、代码块、引用、标题、有序列表、无序列表、分隔线等Markdown标记来对文字进行快速排版，使用方法是“标记符号+空格”，代码块是“```+回车键”。
  除此之外，还可以通过【文档导入】功能，将Markdown文件导入知乎。不过需要注意的是，基础的Markdown语法能被正常解析，但一些扩展语法，如表格、任务列表、删除线等就无法被解析了，它们将以纯文本的形式显示。

小提示： 【文档导入】图标在工具栏的最右边，单击【…】才能看到。

6.3.2 简书

  简书作为一款被广泛使用的写作工具，也支持基础的Markdown语法，在其新建文章界面，通过【设置】→【默认编辑器】可以切换为Markdown编辑器。

6.3.3 CSDN

  写技术博客的人应该都听说过CSDN，它的Markdown编辑器功能已经非常全面，使用Typora编写的Markdown源码（包括表格、公式、流程图、甘特图等），粘贴或导入到CSDN基本上都可以正常显示。
  在【创作中心】可以切换Markdown编辑器和富文本编辑器，在Markdown编辑器中可以直接编写、粘贴或导入Markdown文件，可以将图片拖拽上传，这些都大大提高了博客的写作效率。

6.4 写微信公众号文章

  “再小的个体，也要有自己的品牌”，很多公司、团队和个人都有自己的微信公众号。写过微信公众号文章的朋友可能都遇到过排版问题，使用Markdown虽然方便，但很多格式在微信公众号编辑器中不支持，有些格式支持得也不是很好。
  这里推荐两款在线格式化工具来帮助解决上述排版问题，它们可以将Markdown文档直接渲染成适合微信公众号的格式，并且有多种主题可以选择。

6.4.1 Online-Markdown

  打开https://www.flyzy2005.cn/tools/online-markdown/进入在线编辑页面，可以根据个人喜好调整页面主题和代码主题，还可以实时预览渲染效果，复制渲染后的内容，粘贴到微信公众号的编辑器中，原有的文档格式会得以保持。

6.4.2 Md2All

  Md2All的使用方法跟Online-Markdown差不多，只不过多了一个下载HTML文档的功能。Md2All地址为http://md.aclickall.com/。

6.5 写邮件——Markdown Here

  写邮件是日常工作中最常见的写作场景之一，几乎人人都要写邮件。通常使用Markdown写邮件的步骤是：在Markdown编辑器中写邮件→复制渲染后的内容→粘贴到邮件编辑器→发送邮件。这种方法本身没什么问题，但是操作步骤复杂，一旦邮件内容有修改还得照上面的步骤再操作一次，实在太麻烦。
  Markdown Here帮我们解决了这个问题。它不但能让我们在邮箱中直接使用Markdown写邮件，还可以通过配置样式让邮件内容变得更加美观。
  Markdown Here是一个浏览器/客户端插件，它支持GFM语法，可以一键渲染富文本编辑器中的Markdown语法，这让我们可以使用任意Web编辑器来写邮件。
  Markdown Here提供了适用于Chrome、Firefox、Safari、Opera浏览器的插件和Thunderbird、Postbox邮件客户端插件。下载地址：https://markdown-here.com/get.html。源码地址：https://github.com/adam-p/markdown-here/。

6.5.1 安装Chrome插件

  在Chrome应用商店中，搜索“Markdown Here”，找到后进入安装界面，单击右上角的【+添加至CHROME】安装插件，安装成功后重启Chrome，在右上角会显示Markdown Here图标。

6.5.2 使用Markdown写邮件

  理论上，Markdown Here可以渲染所有Web端富文本编辑器中的Markdown文档，本例就以最常用的163邮箱为例，看看如何使用Markdown来写邮件。

1. 使用Chrome打开163邮箱，在文本编辑器中使用Markdown编写邮件
2. 把光标放在编辑器中，单击Chrome上的Markdown Here图标，渲染编辑器中的内容
3. 发送邮件

  只需要单击浏览器上的Markdown Here图标，就可以把编辑器中的Markdown渲染成HTML格式的文档，再次单击该图标就可以切换回Markdown格式，神奇的Markdown Here把所有的Web编辑器都变成了Markdown编辑器。

6.5.3 自定义主题

  如果你不喜欢Markdown Here的默认主题，也可以自定义主题。在Chrome浏览器的Markdown Here图标上，单击鼠标右键，在弹出的操作列表中单击【选项】进入设置界面。在【基本渲染CSS】中可以自定义Markdown主题，在【语法高亮CSS】中可以选择代码高亮的主题，在【预览】中可以实时查看效果。

把主题改为一款比较流行的主题——markdown-here-css，操作步骤：

1. 打开https://github.com/caseywatts/markdown-here-css。
2. 再打开项目列表中的default.css文件。
3. 复制文件中的所有内容。
4. 粘贴到【基本渲染CSS】中（Markdown Here会自动保存）。
5. 在预览中查看新主题的效果。

  如果你是一名前端开发者，可以尝试定制一款属于自己的主题。而对于普通用户来说，使用现成的主题就好了。
  下面这个项目中收集了一些Markdown Here的主题，大家可以去尝试一下：https://github.com/huanxi007/markdown-here-css

小提示： 如果配置主题时出错了，也不用紧张，【基本渲染CSS】下面有一个【恢复默认】按钮，一键恢复即可。

6.5.4 快捷键

  在Markdown编辑界面和渲染效果界面之间切换，除通过单击Markdown Here图标之外，还可以使用快捷键。

  如果快捷键冲突，可以修改快捷键，方法同样是进入设置界面，找到【快捷键】一栏，对快捷键的设置及其注意事项，一目了然。更多有关Markdown Here的使用技巧，可以参考https://github.com/adam-p/markdown-here/wiki/Tips-and-Tricks。

6.6 其他常见的Markdown工具

6.6.1 便签工具——锤子便签

  锤子便签算是手机上比较有名的便签工具了，它支持简单的Markdown语法，主要应用在文字的排版上。
  在使用时，通过右上角的下拉列表，切换至【Markdown模式】即可；在编辑时，输入法上方会显示一排快速输入工具。
  当使用图片形式分享时，Markdown格式的内容会被渲染，而以文字形式分享或发送邮件发送的都是源码。

6.6.2 日记软件——DayOne

   DayOne 应该是在 Mac 和 iOS 设备上最受欢迎也最好用的日记软件了。它能够在新建日记时自动记录各种比较隐私的信息，如时间、位置、天气等，然后可以通过这些信息或自定义的标签筛选过往的日记。另外DayOne还支持使用Markdown对日记进行排版，使用方法与在线文档相同，通过“标记符号+空格”插入和渲染Markdown格式。
  DayOne支持的Markdown格式主要有标题、加粗、斜体、有序列表、无序列表、任务列表（ [ ] +空格）、引用、代码块（行首输入 ``` + 空格）和分隔线等，其效果如下图所示。

6.6.3 交互式文档工具

  相较于普通的文档，交互式文档最大的不同就是，文档中的代码是可执行的。普通文档插入代码后，代码是“死”的，但交互式文档会执行代码，并显示代码的执行结果。
  想像一下，当你在学习一门编程语言或写技术文章时，只要在文档中输入代码，结果就会直接显示出来，如果代码有变动，结果也会随即改变，这样一来，就再也不用在IDE和文档之间来回切换，复制/粘贴了。
  交互式文档应用最广泛的领域是技术写作、数据分析和机器学习，目前最流行的两个工具是 Jupyter Notebook 和 R Markdown。

1.Jupyter Notebook

  Jupyter Notebook 是一个 Web 交互式文档工具，它使用 Markdown 编写文本，有着类似于 Typora 的所见即所得的功能，不过它的所见即所得还包括代码的即时运行。Jupyter Notebook可以在文档中直接编写和运行代码（支持40多种编程语言），并即时显示运行结果，是集写作、编程及运行于一体的交互式文档工具。
  从名字上看Jupyter是Julia、Python和R的组合，这3种语言是数据分析和机器学习领域非常重要的编程语言，那么，Jupyter的意义也就不言而喻了。由于能完整地展现文本、公式、代码及代码运行的整个过程，目前Jupyter Notebook已经成为技术写作、数据分析和机器学习方面必备的编辑工具。

a. 安装和启动

  Jupyter Notebook的安装方法可访问：https://jupyter.readthedocs.io/en/latest/install.html。页面上方为Jupyter Notebook的简要说明，下方为安装及环境要求。
  在终端启动Jupyter Notebook的命令是jupyter notebook。然后浏览器会自动打开http://localhost:8888/tree，如果没有自动打开，请自已输入该网页地址。

小提示： 默认端口是8888，如果要指定端口，需要加上-port，例如jupyter notebook-port=6666。

b. 创建文档

  在Jupyter Notebook首页上单击右上角的【New】→【Python 3】→进入文档编辑界面（内核是Python 3），如下图所示。
  小提示： Jupyter Notebook默认只安装了Python 3的内核，如果想要安装其他内核请参考https://github.com/jupyter/jupyter/wiki/Jupyter-kernels。

c. 单元类型

  Jupyter Notebook文档是由一系列“单元”组成的，这些“单元”主要分为两类——Markdown文本和代码。它们都可以通过Shift+Enter组合键进行渲染和执行，Markdown单元会直接显示渲染后的效果，代码单元会在其下面显示执行后的结果。单元的默认格式是代码（Code），可以通过工具栏进行切换。
  在Markdown单元中使用Markdown标记来格式化文本，支持GFM语法，可直接显示渲染效果。代码单元用于编写代码（要与内核相匹配），支持代码高亮，可直接显示运行结果。

d. 导出文档

  Jupyter Notebook可通过【菜单栏】→【File】→【Download as】导出HTML、Markdown、PDF、reveal.js幻灯片、reStructuredText、LA TEX等多种格式的文档。

e. 更多内容

更多关于Jupyter Notebook的内容请参考其开源地址：https://github.com/jupyter/notebook和官方文档https://jupyter-notebook.readthedocs.io/en/stable/。

2. R Markdown

  R Markdown，顾名思义就是在Markdown中通过R语言实现交互式文档（现在也支持Python、Bash、SQL等常用语言），在数据分析领域有着举足轻重的地位。

a. 创建文档

  使用R Markdown前需要先安装R语言和RStudio编辑器，然后在RStudio中通过【菜单栏】→【File】→【New】→【R Markdown...】来新建文档（如果是首次使用会先安装rmarkdown包），然后会弹出R Markdown类型选择窗口。

• 文档类型

1. Document：普通文档，可创建HTML、PDF和Word格式的文档，推荐选择HTML格式，因为HTML格式的文档可以随时切换成PDF文档或Word文档。
2. Presentation：幻灯片，可创建HTML和PDF格式的幻灯片。
3. Shiny：交互式文档，可创建交互式文档和交互式幻灯片。
4. From Template：通过模板创建文档。

b. 导出文档

  单击【Knit】会渲染Markdown文本并执行文档中所有的R代码，并把结果追加到代码之后，然后导出HTML（因为我们之前选择的是HTML）文档。
  HTML格式的文档可以随时切换成PDF文档或Word文档，可以通过【Knit】右边的下拉菜单进行切换

小提示： 如果要导出PDF或Word格式的文档需要安装对应的工具，在新建R Markdown时或导出报错时会有相关的提示。

c. 插入代码

  在R Markdown中，可以通过工具栏上的【Inset】插入代码块，目前支持的语言有R、Bash、Python、Rcpp、SQL、Stan。

summary(cars)

  在默认情况下，文档中的代码是未执行的，我们可以选择执行一个代码块或所有代码，执行代码的所有操作可以通过工具栏上【Run】的下拉列表查看。

d. 更多内容

  更多关于R Markdown的内容请参考官方文档https://rmarkdown.rstudio.com/或R Markdown权威指南https://bookdown.org/yihui/rmarkdown。

6.6.4 网页编写工具——md-page

  Markdown文档是可以通过工具转换成HTML文档的，不过这里要经历一次转换，以后若有修改，还得再次进行转换。能否直接使用Markdown来编写网页，而不需要转换呢?可以使用md-page这个项目。
  项目地址：https://github.com/oscarmorrison/md-page。
  在添加md-page.js这个依赖以后，就可以直接使用Markdown来写一些简单的网页了，无须转换格式，直接双击文档即可浏览。

• 具体步骤

1. 使用任意编辑器（推荐VS Code）新建一个HTML文件，如my.html。

2. 在my.html的顶部添加所依赖的JS脚本。

   <script src="https://rawcdn.githack.com/oscarmorrison/md-page/master/md-page.js">
   </script>
   

   注意： 由于网络原因，这个脚本加载起来可能会比较慢，从而严重影响渲染效果。建议从md-page项目中下载md-page.js到本地，并与my.html放在同一个目录中。

   <script src="./md-page.js">
   </script><npscript>
   

3. 使用Markdown编写页面内容。
   现在，就可以使用最熟悉的Markdown来编写页面内容了，编写完成后双击my.html即可查看页面效果。

6.6.5 项目文档写作工具

1. MkDocs

  MkDocs是一款用Python开发的静态站点生成器，它可以快速地创建项目文档。文档的源码使用Markdown编写，配置文件使用YAML编写，能够一键编译成静态站点，使用起来非常方便。
  由于很多开源的项目文档都使用MkDocs编写，如Google的python-fire，因此有必要学习一下。

a. 环境配置

• 安装MkDocs

pip install mkdocs

• 查看MkDocs版本

mkdocs -V

b. 创建项目

# 第一步
mkdocs new project_name
# 第二步
cd project_name
# 第三部
tree

c. 启动服务

  启动服务的命令是 mkdocs serve，然后，在浏览器中打开http://127.0.0.1:8000。在服务器启动后，如果配置文件、文档目录或主题发生改变，则服务器会自动加载变更的结果并生成新的文档。

d. 添加页面

  在MkDocs中，一个Markdown文件被渲染后就是一个页面，因此如果我们想添加页面，就需要先在docs目录下添加一个Markdown文件，文件的后缀名可以是md（推荐）、markdown、mdown、mkdn或mkd。

• 添加页面的实例演示

1. 在docs目录下添加几个Markdown文件
   说明： 文件夹docs的目录结构对应着生成页面的URL路径，

2. 修改配置文件mkdocs.yml

site_name: Grade markdown 
pages:
- 首页: index.md
- 语法: grammer.md
- 规范: standard.md
- Typora: typora.md
- VS Code: vscode.md
- 个人简历: resume.md

1. site_name是站点的名称。
2. 在pages中配置的是导航栏上的页面名称，每一个页面对应一个Markdown文件。

e. 配置主题

  MkDocs的主题是可以配置的，默认主题是mkdocs。如果想切换成别的主题，只要修改theme的值就可以了。

site_name: Grade markdown 
pages:
- 首页: index.md
- 语法: grammer.md
- 规范: standard.md
- Typora: typora.md
- VS Code: vscode.md
- 个人简历: resume.md

theme: mkdocs

  主题分为内置主题、第三方主题和自定义主题，内置主题如上所述，直接配置主题名就可以了。如果是第三方主题，就需要先安装主题再进行配置了，自定义主题需要增添插件、后续操作也稍显复杂，但使用效果并不明显。

f. 生成站点

  如果想发布项目，需要先构建项目，生成一个静态资源站点，构建项目的命令mkdocs bulid。更多内容请参考https://www.mkdocs.org/。

2.VuePress

  VuePress是一个比较新的静态网站生成器，主要用于编写技术文档。它集各家之所长，提供了在Markdown文件中使用Vue组件的功能，集成了Google Analytics，以及基于Git的“最后更新时间”功能。
  VuePress有完整的中文指南，网址为：https://vuepress.vuejs.org/zh/guide/。

6.6.6 付费软件

  如果不考虑手机端写作，Typora和VS Code这两款免费软件完全可以满足我们的需求（多设备同步通过Git实现），不过一些付费软件提供了更专业的服务、更低的使用门槛、更好的用户体验，以及更多的写作平台。

1. 常见付费软件

  目前付费的Markdown软件中最有名的应该是Ulysses、MWeb和Bear（熊掌记）了，它们都是苹果体系产品，都支持Mac、iPad、iPhone设备。
  其中最强大也最贵的当属Ulysses，它比较适合频繁进行文字写作的人，基本上可以满足写作者的一切需求，但是它的Markdown XL语法可能会让你觉得不习惯，也不太通用。
  最符合国人写作习惯的是MWeb，它所支持的语法也是最全面的，例如表格和流程图（Ulysses和Bear都不支持），适合写技术文章比较多的人。
  最年轻、最简洁、最好看，也是性价比最高的当属Bear，它在风格上像年轻版的Ulysses，在电脑和手机端都有非常好的用户体验。这里要重点推荐Bear。

2.Bear

  Bear（熊掌记）是一款非常流行的Markown笔记软件，由于极简的设计风格和友好的交互界面，Bear能够让用户快速上手，然后又爱不释手。
  使用Bear写笔记，最直观的感受就是舒服。它很好地将Markdown和写笔记的需求进行了融合，巧妙地使用标签管理笔记，连新建文件夹都省了；它还提供了Safari、Chrome、Firefox和Opera浏览器的扩展插件，能够“一键下载文章”，该插件地址为：https://bear.app/faq/Extensions/Browserextensions/。
  Bear基础版可单点使用，支持Mac、iPad、iPhone设备；若想多设备同步，则需要使用付费的高级版本 。
  如果用过Typora，应该会觉得Bear很亲切，它们的界面风格有点像。不过Bear在支持Markdown实时渲染的同时，又保留了标记符号，这样比较方便查看和修改，在这一点上，如果你习惯了Typora，可能会觉得有点别扭。

• 关于Bear需要知道如下几点

1. Bear支持“文件”（插入文件）和“标记”（高亮选中的内容）语法，虽然它们在Bear中用起来很方便，但在其他Markdown工具中这两个功能并不常见，所以使用时要考虑其兼容性。
2. 不支持表格、目录、流程图、甘特图、数学公式及各种图表。
3. 不支持大纲视图，如果文章比较长，查看会不太方便。
4. 可直接在Bear中粘贴剪切版中的图片。
5. 若有未执行完的待办事项，会在左边导航栏的【待办事项】中显示，在笔记的标题上会显示“待办事项”的整体进度。
6. 使用两个方括号包裹笔记名是可以链接笔记的，例如[ [ 笔记名 ] ]，在输入 [[ + 空格之后，Bear会给出补全信息。

a. 标记符号

  Bear简单化了“文本格式”的标记符号，但同时也提供了标准格式的兼容模式，可以到偏好设置中开启【兼容Markdown兼容模式】。

b. 调整排版样式

  在排版方面，Bear可以在偏好设置中调节字体大小、行高、行宽和段落间距。

c. 使用标签整理笔记

  在Bear中，可以使用标签归类整理笔记。标签可以放置在笔记中的任何地方，只需要使用#号包裹起来即可，Bear还会自动识别常见标签并添加相应的图标。

d. 手机端写作

  使用Bear在手机端写作与在电脑上写作有同样好的体验。

6.7 本章小结

  本文介绍了很多专业的Markdown工具，以帮助读者更好地应对日常写作，了解了这些，在什么样的场景使用什么样的工具，相信已经胸有成竹了。