Skip to main content

GitBook 组织 Markdown

喜欢用 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 -VCLI version: 2.3.2GitBook 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 initinfo: create section1/README.mdinfo: create section1/example1.mdinfo: create section1/example2.mdinfo: create section2/README.mdinfo: create section2/example1.mdinfo: create SUMMARY.md

2.5 预览文档#

$ gitbook serveLive reload server started on port: 35729Press CTRL+C to quit ...
info: 7 plugins are installedinfo: loading plugin "livereload"... OKinfo: loading plugin "highlight"... OKinfo: loading plugin "search"... OKinfo: loading plugin "lunr"... OKinfo: loading plugin "sharing"... OKinfo: loading plugin "fontsettings"... OKinfo: loading plugin "theme-default"... OKinfo: found 6 pagesinfo: found 0 asset filesinfo: >> 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 --versionebook-convert (calibre 4.17.0)Created by: Kovid Goyal <kovid@kovidgoyal.net>

3.2 生成 PDF 文档#

$ gitbook pdf ./ ./mybook.pdfinfo: 7 plugins are installedinfo: 6 explicitly listedinfo: loading plugin "highlight"... OKinfo: loading plugin "search"... OKinfo: loading plugin "lunr"... OKinfo: loading plugin "sharing"... OKinfo: loading plugin "fontsettings"... OKinfo: loading plugin "theme-default"... OKinfo: found 6 pagesinfo: found 1 asset filesinfo: >> generation finished with success in 5.7s !info: >> 1 file(s) generated

3.3 生成 ePub 文档#

$ gitbook epub ./ ./mybook.epubinfo: 7 plugins are installedinfo: 6 explicitly listedinfo: loading plugin "highlight"... OKinfo: loading plugin "search"... OKinfo: loading plugin "lunr"... OKinfo: loading plugin "sharing"... OKinfo: loading plugin "fontsettings"... OKinfo: loading plugin "theme-default"... OKinfo: found 6 pagesinfo: found 1 asset filesinfo: >> generation finished with success in 1.9s !info: >> 1 file(s) generated

3.4 生成 MOBI 文档#

$ gitbook mobi ./ ./mybook.mobiinfo: 7 plugins are installedinfo: 6 explicitly listedinfo: loading plugin "highlight"... OKinfo: loading plugin "search"... OKinfo: loading plugin "lunr"... OKinfo: loading plugin "sharing"... OKinfo: loading plugin "fontsettings"... OKinfo: loading plugin "theme-default"... OKinfo: found 6 pagesinfo: found 1 asset filesinfo: >> generation finished with success in 1.6s !info: >> 1 file(s) generated

3.5 PDF 预览效果#