喜欢用 Markdown 写文档,那怎么把一个个 Markdown 文档组成在一起呢?

这篇文章,分享了一个用 GitBook 来组织 Markdown 文档的办法。一起了解下吧。

Markdown 是一种轻量级标记语言。只需人们纯文本编写文档,加上点标记符号,就能转成有格式的文档(如 HTML 富文本)。已广泛应用在笔记、文档、博客、出书等。2016 年 RFC 7763 开始也引入了 MIME 类型 text/markdown

1 准备工具

  1. 安装 Node.js: https://nodejs.org/
  2. 安装 GitBook: https://www.npmjs.com/package/gitbook
npm install gitbook-cli -g

最终,终端里可执行 gitbook :

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

2 准备文档

2.1 创建文档目录

mkdir start-gitbook

2.2 创建说明文件 README.md

README.md 是 GitBook 的必要文件

echo "# My GitBook" > README.md

2.3 创建目录文件 SUMMARY.md

SUMMARY.md 是 GitBook 的必要文件

cat <<EOF > SUMMARY.md
# Summary This is the summary of my book. * [section 1](section1/README.md)
* [example 1](section1/example1.md)
* [example 2](section1/example2.md)
* [section 2](section2/README.md)
* [example 1](section2/example1.md)
EOF

编辑组织已经存在的 Markdown 文档路径。新建的项目,则写预想的文档结构。

2.4 创建文档结构

依照 SUMMARY.md ,创建新项目的文档结构。

$ gitbook init
info: create section1/README.md
info: create section1/example1.md
info: create section1/example2.md
info: create section2/README.md
info: create section2/example1.md
info: create SUMMARY.md

2.5 预览文档

$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ... info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 0 asset files
info: >> generation finished with success in 0.5s ! Starting server ...
Serving book on http://localhost:4000

浏览器打开 http://localhost:4000 ,即可预览。效果如下:

3 生成文档

默认生成 HTML 文档,在 _book 目录。如果要生成其他格式,需要安装 ebook-convert 插件。

3.1 安装 ebook-convert 插件

安装 Calibre: https://calibre-ebook.com/download ,并配置好终端 ebook-convert 命令。

Ubuntu 直接安装:

sudo aptitude install calibre

macOS 下载安装,并配置软链接:

ln -s /Users/John/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin

最终,终端里可执行 ebook-convert :

$ ebook-convert --version
ebook-convert (calibre 4.17.0)
Created by: Kovid Goyal <kovid@kovidgoyal.net>

3.2 生成 PDF 文档

$ gitbook pdf ./ ./mybook.pdf
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 5.7s !
info: >> 1 file(s) generated

3.3 生成 ePub 文档

$ gitbook epub ./ ./mybook.epub
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 1.9s !
info: >> 1 file(s) generated

3.4 生成 MOBI 文档

$ gitbook mobi ./ ./mybook.mobi
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 1.6s !
info: >> 1 file(s) generated

3.5 PDF 预览效果

结语

Go coding!

小技巧:用 GitBook 组织 Markdown 文档的更多相关文章

  1. Markdown 文档生成工具

    之前用了很多Markdown 文档生成工具,发现有几个挺好用的,现在整理出来,方便大家快速学习. loppo: 非常简单的静态站点生成器 idoc:简单的文档生成工具 gitbook:大名鼎鼎的文档协 ...

  2. 编辑技巧之如何跟PDF文档添加贝茨编号

    除了office办公软件,pdf文档现在使用的频率也便多了,不论是工作或是学习,阅读都用阅读器打开就行了,可是如果想要修改.编辑那只用阅读器是无法进行编辑的,其实PDF文件的编辑还是很方便,使用PDF ...

  3. 01将图片嵌入到Markdown文档中

    将图片内嵌入Markdown文档中 将图片嵌入Markdown文档中一直是一个比较麻烦的事情.通常的做法是将图片存入本地某个路径或者网络存储空间,使用URL链接的形式插入图片: ![image][ur ...

  4. C#解析Markdown文档,实现替换图片链接操作

    前言 又是好久没写博客了 其实也不是没写,是最近在「做一个博客」,从2月21日开始,大概一个多星期的时间,疯狂刷进度,边写代码边写了一整系列的博客开发笔记,目前为止已经写了16篇了,然后上3月之后工作 ...

  5. python实现解析markdown文档中的图片,并且保存到本地~

    背景 前阵子简书好像说是凉了,搞得我有点小慌,毕竟我的大部分博客都是放在简书上面的,虽然简书提供了打包导出功能,但是只能导出文字,图片的话还是存在简书服务器上面,再加上我一直想要重新做一个个人博客,于 ...

  6. 使用Python从Markdown文档中自动生成标题导航

    概述 知识与思路 代码实现 概述 Markdown 很适合于技术写作,因为技术写作并不需要花哨的排版和内容, 只要内容生动而严谨,文笔朴实而优美. 为了编写对读者更友好的文章,有必要生成文章的标题导航 ...

  7. Linux(Ubuntu)使用日记------markdown文档转化为word文档

    Linux(Ubuntu)使用日记------markdown文档转化为word文档

  8. 将markdown文档使用gulp转换为HTML【附带两套css样式】

    将markdown文档使用gulp转换为HTML[附带两套css样式] 今天遇到一个需求,即将Markdown文档转为为HTML在网页展示,身为一名程序员,能用代码解决的问题,手动打一遍无疑是可耻的. ...

  9. 如何在Markdown文档中插入空格?

    简单说 在 Markdown 文档中,可以直接采用 HTML 标记插入空格(blank space),而且无需任何其他前缀或分隔符.具体如下所示: 插入一个空格 (non-breaking space ...

随机推荐

  1. D. Kefa and Dishes(状压)

    永久打开的传送门 \(这次总算没有写砸........\) \(设f[i][j]为上一次吃的i物品状态为j的最大收益\) \(那么我们就暴力枚举所有状态i,然后在当前状态找出一个没吃的食物j,再去找一 ...

  2. C. Two Arrays(思维DP或组合数学)

    \(首先很容易想到一个O(n^4m)的DP\) \(设dp\ [i]\ [j]\ [q]\ 为长度i,a数组以j结尾,b数组以q结尾(q>=j)\) for(int i=1;i<=n;i+ ...

  3. spring boot的核心注解

    1.@SpringBootApplication 是SpingBoot的启动类 此注解等同于@Configuration+@EnableAutoConfiguration+@ComponentScan ...

  4. Prime Path素数筛与BFS动态规划

    埃拉托斯特尼筛法(sieve of Eratosthenes ) 是古希腊数学家埃拉托斯特尼发明的计算素数的方法.对于求解不大于n的所有素数,我们先找出sqrt(n)内的所有素数p1到pk,其中k = ...

  5. NFS服务器搭建-共享PC与ARM主板文件

    NFS服务器搭建-共享PC与ARM主板文件 在搭建好交叉编译环境之后需要实现目标板与宿主机的文件共享,在这里选择NFS,由于资料较多.需要注意的以下几点: 目标板与宿主机需要连接在同一个网段内. 宿主 ...

  6. MongoDB介绍及开发指南

    目录 一.MongoDB介绍 二.搭建MongoDB 三.Java With MongoDB 四.Spring Session MongoDB 五.MongoDB开发规范及示例 六.MongoDB + ...

  7. gather函数

    gather(input, dim, index):根据  index,在  dim  维度上选取数据,输出的  size  与  index  一致 # input (Tensor) – 源张量 # ...

  8. ABP框架踩过的坑系列6

    ABP框架踩过的坑系列6 应是无事.齐侯方才的确到了吴纠庭院https://www.mixcloud.com/ltTFvU888smi8jS/几日行军劳顿其实齐侯本应该睡下了https://www.m ...

  9. Postman学习之Authorization

    前言:本章将学习Postman当中的授权——Authorization 一.简介 Authorization顾名思义就是授权的意思,那是给谁授权呢?又有多少种授权的方式呢?Authorization是 ...

  10. mybatis中的动态SQL(IF Chooes When Where Set ForEach SQL片段)

    mapper: public interface BlogMapper { List<Blog> getBlogByIF(Map map); } IF <select id=&quo ...