标签 Blog 下的文章

基于Markdown格式的电子书生成工具大比拼:gohugo、mdbook和peach

基于Markdown格式文件写博客已经很多年了,一直使用的是Wordpress的markdown插件,由于各种遗留原因,一直没有转换到直接使用静态站点的方式。博客文章之间一般来说多是独立篇章,少有关联,即便是写一个系列文章,数量也不会太多。因此,用博客形式来组织书籍章节是不大合适的。“术业有专攻”,我们还得寻找专门用来制作电子书的工具或平台,并且要支持本地安装,支持基于Markdown格式的源数据文件。

专门用于制作电子书类文档的知名工具包括:gitbookRead the Docs。不过前者的开源版本2018年末就不更新了,而Read the Docs则比较老,还需要多个工具配合。我个人倾向于单个二进制文件搞定一切。于是我找到了三个候选:gohugomdbookpeach,这三个候选部署时都只有一个二进制文件。gohugo和peach是Go语言实现的,而mdbook则是用Rust语言实现的。下面我们就来简单对比一下这三个基于Markdown格式的电子书制作工具。

1. mdbook

mdbook是模仿gitbook样式的从markdown文件生成电子书的工具和静态站点服务,它仅聚焦于“电子书制作和站点服务”。如果不是类似gitbook风格的其他类静态内容服务,那么它并不适合。因此,该工具采用了惯例优先原则(convention over configuration),使得使用时我们无需做太多的配置即可生成一个像模像样的电子书站点。

由于是rust实现的,mdbook本地部署时只需一个二进制文件,我们直接从它的github release上下载对应os平台的release文件(这里是macos的0.4.0版本):

wget -c https://github.com/rust-lang/mdBook/releases/download/v0.4.0/mdbook-v0.4.0-x86_64-apple-darwin.tar.gz

解压后,将mdbook所在路径添加到PATH环境变量中:

$tar zxvf mdbook-v0.4.0-x86_64-apple-darwin.tar.gz
x mdbook
$ls
mdbook*                        mdbook-v0.4.0-x86_64-apple-darwin.tar.gz

$mdbook -help
mdbook v0.4.0
Mathieu David <mathieudavid@mathieudavid.org>
Creates a book from markdown files

USAGE:
    mdbook [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    build    Builds a book from its markdown files
    clean    Deletes a built book
    help     Prints this message or the help of the given subcommand(s)
    init     Creates the boilerplate structure and files for a new book
    serve    Serves a book at http://localhost:3000, and rebuilds it on changes
    test     Tests that a book's Rust code samples compile
    watch    Watches a book's files and rebuilds it on changes

For more information about a specific command, try `mdbook <command> --help`
The source code for mdBook is available at: https://github.com/rust-lang/mdBook

接下来,我们就使用mdbook init命令创建一个电子书工程:

$mdbook init go-ml

Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book?
go machine learning
2020-06-27 15:58:03 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

我们看到mdbook init生成了一个目录,目录布局如下:

➜  /Users/tonybai/MyEbook/mdbook git:(master) ✗ $tree
.
└── go-ml
    ├── book
    ├── book.toml
    └── src
        ├── SUMMARY.md
        └── chapter_1.md

3 directories, 3 files

接下来,我们直接运行mdbook serve即启动了一个服务,用于访问该电子书:

➜  /Users/tonybai/MyEbook/mdbook git:(master) ✗ $mdbook serve go-ml
2020-06-27 16:06:56 [INFO] (mdbook::book): Book building has started
2020-06-27 16:06:56 [INFO] (mdbook::book): Running the html backend
2020-06-27 16:06:56 [INFO] (mdbook::cmd::serve): Serving on: http://localhost:3000
2020-06-27 16:06:56 [INFO] (warp::server): listening on http://[::1]:3000
2020-06-27 16:06:56 [INFO] (mdbook::cmd::watch): Listening for changes...

我们通过浏览器访问http://localhost:3000,可以看到如下页面:

img{512x368}

图:mdbook生成的电子书首页

我们看到:我们没有做任何配置就生成了一个和gitbook样式差不多的电子书服务站点。该站点还支持选择页面显示模式(截图中使用的是默认的Light模式)、支持查询等。

如果我们要增加新章节、编排章节标题缩进,只需编辑电子书工程下面的src/SUMMARY.md

$cat SUMMARY.md
# Summary

- [Chapter 1](./chapter_1.md)
  - [Chapter 1.1](./chapter_1_1.md)
- [Chapter 2](./chapter_2.md)

这些对于多数人来说已经是足够了的,后续只需关注书籍内容即可,无需对mdbook生成的工程进行什么调整。mdbook会自动探测src目录下的文件变化并根据变化重新生成静态html文件。我们只需刷新页面即可看到最新变化。

2. peach

peach是一款由Go语言实现的多语言、实时同步以及全文搜索功能的 Web 文档服务器。它由gogs的作者无闻打造,该作者的很多开源项目的文档也都是由peach生成和提供文档服务支撑的。
我们可以直接使用go get安装peach:

$export GONOSUMDB="github.com/russross/blackfriday"
$go get github.com/peachdocs/peach
go: github.com/peachdocs/peach upgrade => v0.9.8
$peach -v
Peach version 0.9.8.0810

接下来,我们用peach建立电子书工程:

$peach new -target=go-ml.peach
➜  Creating 'go-ml.peach'...
➜  Creating 'templates'...
➜  Creating 'public'...
Do you want to use custom templates?[Y/n] n
✓  Done!

我们这里直接使用peach项目自身文档的自定义模板:

下载配置好的自定义模板:

$ cd go-ml.peach

$ git clone https://github.com/peachdocs/peach.peach.git custom
Cloning into 'custom'...
remote: Enumerating objects: 62, done.
remote: Total 62 (delta 0), reused 0 (delta 0), pack-reused 62
Unpacking objects: 100% (62/62), done.
Checking connectivity... done.

启动web服务:

$peach web

intro/
     |__ installation
     |__ getting_started
     |__ roadmap
howto/
     |__ documentation
     |__ webhook
     |__ templates
     |__ static_resources
     |__ navbar
     |__ pages
     |__ extension
     |__ protect_resources
     |__ upgrade
advanced/
        |__ config_cheat_sheet
faqs/
intro/
     |__ installation
     |__ getting_started
     |__ roadmap
howto/
     |__ documentation
     |__ webhook
     |__ templates
     |__ static_resources
     |__ navbar
     |__ pages
     |__ extension
     |__ protect_resources
     |__ upgrade
advanced/
        |__ config_cheat_sheet
faqs/
[Peach] 20-06-27 10:17:31 [ INFO] Peach 0.9.8.0810
[Peach] 20-06-27 10:17:31 [ INFO] Peach Server Listen on 127.0.0.1:5556

我们通过浏览器访问http://localhost:5556,可以看到如下页面:

img{512x368}

图:peach生成的电子书目录页

不过,和mdbook不同,上面peach加载并渲染的文档并不在本地,我们在custom/app.ini中看到如下配置:

[docs]
TYPE = remote
TARGET = https://github.com/peachdocs/docs.git
SECRET = peach

我们看到当前例子采用了remote模式,即使用Github上的仓库peachdocs/docs中的数据(markdown文件)作为源文件进行渲染,而这个仓库的结构如下:

$tree -L 2 docs
docs
├── TOC.ini
├── en-US
│   ├── advanced
│   ├── faqs
│   ├── howto
│   └── intro
├── images
│   └── github_webhook.png
└── zh-CN
    ├── advanced
    ├── faqs
    ├── howto
    └── intro

11 directories, 2 files

TOC.ini文件描述了文档结构布局:

$cat TOC.ini
-: intro
-: howto
-: advanced
-: faqs

[intro]
-: README
-: installation
-: getting_started
-: roadmap

[howto]
-: README
-: documentation
-: webhook
-: templates
-: static_resources
-: navbar
-: pages
-: extension
-: protect_resources
-: upgrade

[advanced]
-: README
-: config_cheat_sheet

[faqs]
-: README

我们看到,和mdbook相比,peach的门槛稍高一些,需要学习TOC.ini中的特殊配置语法,同时如果要改变peach的默认风格,还要学习peach使用的模板语法(Peach 使用 Go 语言 Pongo2 v3 版本 作为模板引擎,它使用的是 Django HTML 格式)。

3. gohugo+git book theme

gohugo是这几年最火的静态站点生成工具。和上面两个工具不同的是:它致力于成为一个通用的静态站点工具,与hexo等目标一致。结合gohugo与git book风格的theme也能实现电子书制作与站点服务。

经过多年发展,gohugo的安装十分方便:在macos上,我们既可以使用go get安装(gohugo支持module),也可以使用brew安装:

“`

$brew install hugo

==> Downloading https://mirrors.ustc.edu.cn/homebrew-bottles/bottles/hugo-0.69.2.mojave.bottle.tar.gz

==> Summary

Go官方发布的go.dev给gopher们带来了什么

众所周知,Go是一个诞生于Google内部的编程语言,它在2009年11月份开源,在开源后立即受到了来自全世界开发人员的关注与贡献。但初期的Go语言的发展依旧是由Go核心团队的若干leader决定的,这种类“民主集中制”的方法延续了若干年。直到Go核心团队逐渐意识到Go应该更多倾听社区的声音,并让更多的gopher参与到Go项目的开发和贡献中来,甚至影响和决定一些语言特定的演化。于是Go团队开始特意为Go社区发展招兵买马。像Steve FranciaFrancesc Campoy(后已经从google离职加入Dgraph)等都是在这个阶段加入Go team的。

Go团队在很长一段时间里尤其重视与社区的互动,比如连续多年发起Go user调查Gophercon大会后的Go team与社区的见面会和分组讨论去GOPATH降低Go入门学习曲线发布Go新品牌标识、添加Go module机制改善官网等。

在今天Go官博发文:“Go.dev: a new hub for Go developers”,正式发布go.dev站点,该站点被Go核心团队寄望于成为全世界Gopher开发人员的中心。它将告诉gopher(无论新手还是老油条):谁在使用Go、用Go做什么、怎么学习Go(Go的各种学习资源、受欢迎的Go package都有哪些以及这些package的详细信息)。

img{512x368}

go.dev发布之后,golang.org官网将更加聚焦go开源项目本身的开发、语言演化以及Go版本发布。而go.dev将成为gopher日常使用go语言的中心,包括go学习、go方案、go应用案例等。在这里我们简单探索一下go.dev这个站点究竟给gopher们带来了什么(这仅仅是go.dev的最小功能发布,后续go.dev可能会演化出更多特性、并根据社区反馈更好满足gopher需求)。

一. 学习资源聚合

go.dev的一个重要功能就是帮助首次进入Go世界的开发人员学习Go

在go.dev的”learn”栏目下,我们在第一屏就看到了Go新手入门的三个步骤:安装、”Hello World”、Go tour以及更为详尽文档的入口

img{512x368}

接下来,go.dev提供了这些年口碑较好、受到gopher欢迎的一些初级在线学习资源:

img{512x368}

像gobyexample.com、gophercises.com都在推荐行列。

Go技术类书籍以及培训资源是gopher学习Go过程中不可缺少的:

img{512x368}

Go.dev在learn栏目下推荐了一些口碑不错的Go书籍,比如:Alan A. A. Donovan和Brian W. Kernighan合著的Go圣经:《The Go Programming Language》被在首位推荐。知名Go培训师William Kennedy的培训也被推荐给了大家。不过口碑不错的书籍《Go in action》我觉得也应该列入推荐行列。

在Learn栏目最后,是全世界各地近期有关Go的meetup活动的schedule,Gopher可以得到最及时的meetup信息,并选择参加。

二. 成熟解决方案参考

img{512x368}

go.dev开辟的”solution”栏目旨在提升go的开发过程。栏目从“云原生和网络服务开发”、“命令行程序开发”、“web开发”以及Devops/Site Reliability四个方面提供聚合化的资料。以“云原生和网络服务开发”为例,Go.dev提供了这方面的典型项目和用户、使用方法、关键方案(一些书籍、成熟框架、客户端库以及其他资源)。

go.dev solution栏目还提供了一些Go的典型客户以及这些客户使用Go的典型案例:

img{512x368}

三、Package信息聚合中心

在go.dev的“explore”栏目下,我们看到的是Go package的信息中心:

img{512x368}

就如上图所示,这里提供了受欢迎的package和特色package的推荐列表,以及package信息的搜索功能。

logrus为例

img{512x368}

logrus包的主页,我们看到了有关logrus的各种信息,项目repo地址、最新版本号、module名字、开源许可证信息、文档(应该是集成了godoc返回的结果)、它的依赖、以及以它为依赖的项目(见下图):

img{512x368}

四. 小结

go.dev目前处于最小产品状态(mvp),从目前已经提供的栏目来看,go.dev能为gopher提供的帮助已经很全面了。后续go.dev站点的运营好坏(比如:信息更新是否及时等)将决定go.dev是否能达到其预期的期望。

go.dev目前似乎还缺少论坛功能。不过已有的golang-nutsgobridge已经承担了这个角色,但如果能有一个官方论坛(一站式)就再好不过了。

go.dev在国内可以访问,就是速度有些慢(可能因地区而异)。


我的网课“Kubernetes实战:高可用集群搭建、配置、运维与应用”在慕课网上线了,感谢小伙伴们学习支持!

我爱发短信:企业级短信平台定制开发专家 https://51smspush.com/
smspush : 可部署在企业内部的定制化短信平台,三网覆盖,不惧大并发接入,可定制扩展; 短信内容你来定,不再受约束, 接口丰富,支持长短信,签名可选。

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式:

微博:https://weibo.com/bigwhite20xx
微信公众号:iamtonybai
博客:tonybai.com
github: https://github.com/bigwhite

微信赞赏:
img{512x368}

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! 图片广告位1 图片广告位2 图片广告位3 商务合作请联系bigwhite.cn AT aliyun.com

欢迎使用邮件订阅我的博客

输入邮箱订阅本站,只要有新文章发布,就会第一时间发送邮件通知你哦!

这里是 Tony Bai的个人Blog,欢迎访问、订阅和留言! 订阅Feed请点击上面图片

如果您觉得这里的文章对您有帮助,请扫描上方二维码进行捐赠 ,加油后的Tony Bai将会为您呈现更多精彩的文章,谢谢!

如果您希望通过微信捐赠,请用微信客户端扫描下方赞赏码:

如果您希望通过比特币或以太币捐赠,可以扫描下方二维码:

比特币:

以太币:

如果您喜欢通过微信浏览本站内容,可以扫描下方二维码,订阅本站官方微信订阅号“iamtonybai”;点击二维码,可直达本人官方微博主页^_^:
本站Powered by Digital Ocean VPS。
选择Digital Ocean VPS主机,即可获得10美元现金充值,可 免费使用两个月哟! 著名主机提供商Linode 10$优惠码:linode10,在 这里注册即可免费获 得。阿里云推荐码: 1WFZ0V立享9折!


View Tony Bai's profile on LinkedIn

文章

评论

  • 正在加载...

分类

标签

归档



View My Stats