使用Markdown和Gitbook写文档（gitbook markdown）

- 1 -

Markdown是什么

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。

Markdown是由John Gruber在Aaron Swartz的帮助下开发，并在2004年发布的标记语言。其设计灵感主要来源于纯文本电子邮件的格式，目标是让人们能够使用易读、易写的纯文本格式编写文档。Markdown 编写的文档可以导出 HTML 、PDF、Word、图像、ePub 等多种格式的文档。

下边是一个例子：

Markdown

# 一级标题

## 二级标题

段落1段落1段落1段落1。

段落2段落2段落2段落2段落2。

1. 列表1
2. 列表2
3. 列表3

图片：![](panda.jpg)

输出的HTML

<h1 id='一级标题'>
  <span>一级标题</span>
</h1>
<h2 id='二级标题'>
  <span>二级标题</span>
</h2>
<p><span>段落1段落1段落1段落1。</span></p>
<p><span>段落2段落2段落2段落2段落2。</span></p>
<ol start=''>
  <li><span>列表1</span></li>
  <li><span>列表2</span></li>
  <li><span>列表3</span></li>
</ol>
<p><span>图片：</span></p>
<p><img src="panda.jpg" referrerpolicy="no-referrer"></p>

在浏览器中的渲染效果

- 2 -

Gitbook又是什么

用Markdown写出来的是一篇文章，Gitbook用来将一篇篇的文章组合起来形成一本书。

GitBook可以将编写的内容变成一个网站，像这样：

或者PDF输出，像这样：

- 3 -

能解决什么问题

写文档的方法有很多，比如: MS Word，为什么要用Markdown来写文档？下边是Markdown/Gitbook的益处：

轻量级编辑，能与文件系统和版本管理系统很好地集成

与MS Word相比，Markdown的编辑器属于轻量级编辑器，而且可以选择的编辑器很多，比如：Tyopra, MarkdownPad， VS Code等。

Markdown文件是纯文本文件，能与版本管理系统（如SVN和GIT）配合，实现文件的版本管理。

如果加上一个项目管理软件，如：Redmine, WorkTile或者JIRA，能够实现团队协同工作。

支持内容重用

编辑时专注于内容而不是样式，输出时样式的一致性

在MS Word中编辑文档，用户需要关注内容的同时要调整字体大小、位置、对齐等样式。在Markdown中，样式是既定的，用户编写时专注于内容而不用花精力在样式上。

在输出时，团队中不同的成员使用Markdown编写的内容输出是一样的。

单一数据源，多渠道发布

内容保存成Markdown格式，可以发布成多种输出格式，包括：PDF，HTML，网站，Word，ePub等格式。适合用来打印和在不同屏幕的设备上阅读。

直接搭建成网站，适合在电脑和移动设备上阅读

通过Gitbook，编写的内容即刻变成一个网站，适合人们使用电脑或者手机通过网络访问。

Gitbook有丰富的插件

通过插件，可以修改网站的功能和加入公司的品牌信息（Logo、公司名称、公司文档风格等）

总体成本低

NodeJS, Markdown和Gitbook是免费的。

学习使用Markdown编辑文档的学习曲线平缓，学习成本低。

Gitbook默认提供一套输出，如果能接受这套输出格式，无客户化样式的成本。

- 4 -

上手实践

这部分我们一起来动手在一台Windows电脑上搭建Gitbook的编辑环境，并编写一本书。

1). 搭建环境

安装NodeJS和Gitbook

Gitbook是一个基于NodeJS的命令行工具，所以要先安装NodeJS。

步骤：

1. 下载和安装NodeJS

下载地址：https://nodejs.org/en/，找到并下载对应平台的版本，然后安装即可。

2. 打开Windows的命令行程序，然后运行以下命令安装Gitbook：

npm install -g gitbook-cli

运行结果：

安装Typora

Typora是一个Markdown编辑器，用于编辑Markdown文档。

下载和安装Typora，下载地址:

https://www.typora.io/

2). 编写文档

本文以阿里云的“云服务器 ECS”文档为例，原文请参考：

https://help.aliyun.com/

注意：在资源管理器中建立一个目录，比如我的是：D:\work\markdown\aliyundoc，以下命令需要在这个目录中执行。

1. 在命令行程序中运行以下命令，以初始化一个文档

gitbook init

目录中会生成两个文件：

README.md - 书籍的介绍在这个文件里
SUMMARY.md - 书籍的目录结构在这里配置

2. 在Typora中打开SUMMARY.md文件，并填入以下内容

# Summary

* [简介](README.md)
* [动态与公告](Chapter1/README.md)
    * [新功能发布记录](Chapter1/新功能发布记录.md)
* [产品简介](Chapter2/README.md)
    * [什么是云服务器ECS](Chapter2/什么是云服务器ECS.md)
    * [产品优势](Chapter2/产品优势.md)
    * [应用场景](Chapter2/应用场景.md)
* [产品计费](Chapter3/README.md)
    * [计费概述](Chapter3/计费概述.md)
    * [计费项](Chapter3/计费项.md)
    * [计费方式](Chapter3/计费方式.md)
* [快速入门](Chapter4/README.md)
    * [ECS入门概述](Chapter4/ECS入门概述.md)
    * [通过控制台使用ECS实例](Chapter4/通过控制台使用ECS实例.md)
    * [通过CLI使用ECS实例](Chapter4/通过CLI使用ECS实例.md)

3. 在命令行中再次运行以下初始化命令

gitbook init

此命令会根据SUMMARY.md文件中的内容生成目录和相关的文件：

4. 在每个目录下的md文件中填入内容

使用Tyopra打开文件，然后填入相应的内容，比如：

5. 启动Gitbook服务，查看文档

Gitbook自带一个引擎，通过启动Gitbook服务，将我们编写好的内容发布成一个网站。

1. 在命令行中执行以下命令来启动Gitbook服务

gitbook serve

应该能看到这样的结果：

2. 打开浏览器，然后访问：http://localhost:4000

效果如下：

如果通过手机的浏览器访问，效果是这样的：

- 5 -

参考资料

Markdown语法教程： https://www.runoob.com/markdown/md-tutorial.html
了不起的Markdown：https://item.jd.com/12669274.html

网站首页 > 技术文章正文

猜你喜欢

网站首页 > 技术文章 正文

使用Markdown和Gitbook写文档（gitbook markdown）

猜你喜欢

网站首页 > 技术文章正文