gitbookword-gitnote
- 1 -
Markdown是什么
Markdown 是一种轻量级标记语言gitbookword,它允许人们使用易读易写gitbookword的纯文本格式编写文档。
Markdown是由John Gruber在Aaron Swartz的帮助下开发,并在2004年发布的标记语言。其设计灵感主要来源于纯文本电子邮件的格式,目标是让人们能够使用易读、易写的纯文本格式编写文档。Markdown 编写的文档可以导出 HTML 、PDF、Word、图像、ePub 等多种格式的文档。
下边是一个例子gitbookword:
Markdown
# 一级标题## 二级标题段落1段落1段落1段落1。段落2段落2段落2段落2段落2。1. 列表12. 列表23. 列表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,能够实现团队协同工作。
支持内容重用使用Markdown/Gitbook,内容被拆分成小颗粒的文件。对于在多处出现的内容,比如:版权声明,只需要编写一次,然后在多处被引用。
编辑时专注于内容而不是样式,输出时样式的一致性在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