标签 博客 下的文章

基于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

给女儿搭建一个博客站点

时光荏苒。转眼间女儿已经成为一名小学生了,依稀还记得当年果果呱呱坠地的情景,独自回味,感慨万千。

果果3岁前,都是我来记录她的生活点滴和成长历程,那个时候她是我们生活舞台的主角。3岁后,果果学会了说话,上了幼儿园,开始学习各种知识、技能以及各种才艺。尤其是在幼儿园中班之后,她学会了写字、组词、造句和写日记,果果完全可以自己用文字来表达自己了! 我觉得是时候让她自己来记录她的成长历程了,我和她妈妈只是辅助和指导就好了。这种想法日益迫切,尤其是果果今年上了小学后,果果的成长更快了。我觉得迫切需要给她一个平台去表达她自己和记录她的成长。传统手段不能满足需求,于是我就想到给她搭建了一个博客站点,辅助她用网络文字、图片的形式记录自6岁上学之后的成长历程。于是这个周末就花了些时间,给女儿搭了一个博客站点。

下面以“流水账”的形式,记录一下这个站点的搭建过程,也许能给和我有同样需求的家长们带来一些帮助^_^。

一、选型和准备工作

博客站点,我首选静态页面的。静态页面,又要快速搭建,我首选github page。github page一般情况下在国内访问相对较为稳定,访问速度也不错,ping延迟一般在100多ms,比我独立购买的Digital Ocean的主机的延迟低很多。还有另外一个原因就是市面上几乎所有主流静态页面生成工具都对github pages有着不错的支持。由于采用静态页面,即便将来迁移到VPS,也几乎是无缝的。于是给果果在github上申请了账号

用与搭建博客、个人站点的静态页面生成工具很多,比如:jekylloctopresshexo以及hugo,用哪个呢?作为Gopher,我首选hugo。接下来,我们来看看用hugo是否能搭建出满足我们需求的基于github page的博客站点吧。

hugo的安装参考hugo github主页上的说明即可。由于hugo import了很多第三方package,有些package可能在墙外,因此配置上加速器是更好的、更快的^_^。

二、基于hugo搭建博客站点

去年曾写过一篇《使用Hugo搭建静态站点(http://tonybai.com/2015/09/23/intro-of-gohugo/)》,讲述如何通过hugo这个golang开发的工具搭建一个属于自己的静态站点(static websites)。不过那篇文章并没有谈到hugo如何与github page结合。

hugo官方文档中,对如何使用hugo创建基于github page站点有着较为详尽的描述,这是由一位名为Spencer Lyon的外国开发者贡献的文章,并且Spencer Lyon给出hugo github page的工程template: hugo-gh-blog。我这里就直接使用了该工程模板,并基于hugo_gh_blog做一些定制化修改,比如“汉化”之类的。

下面是详细的步骤:

1、clone hugo_gh_blog

我们首先将Spencer Lyon的hugo_gh_blog代码库clone到本地,这是我们博客搭建的基础:

$mkdir GuoGuoBlog
$cd GuoGuoBlog
$git clone https://github.com/spencerlyon2/hugo_gh_blog.git
Cloning into 'hugo_gh_blog'...
remote: Counting objects: 489, done.
remote: Total 489 (delta 0), reused 0 (delta 0), pack-reused 489
Receiving objects: 100% (489/489), 84.50 KiB | 24.00 KiB/s, done.
Resolving deltas: 100% (232/232), done.
Checking connectivity... done.
$cd hugo_gh_blog/
$ls
LICENSE        README.md    config.yaml    content/    deploy.sh*    static/        themes/

2、编辑config.yaml和本地调试

进入hugo_gh_blog目录,编辑config.yaml,设置站点的一些元数据:

---
contentdir: "content"
layoutdir: "layouts"
publishdir: "public"
indexes:
  category: "categories"
baseurl: "http://baisibei.github.io"
title: "果果的成长历程"
canonifyurls: true
theme: "Lanyon"
...

接下来,我们来生成我们的静态博客页面:

$hugo
0 draft content
0 future content
2 pages created
0 paginator pages created
2 categories created
in 48 ms

hugo将创建public目录,并将生成的页面放入该目录:

$ls public
404.html    categories/    css/        favicon.ico    img/        index.html    index.xml    posts/        sitemap.xml

public/index.html就是站点首页。

我们在本地可以启动hugo server,并查看生成的站点情况:

$hugo server -t Lanyon
0 draft content
0 future content
2 pages created
0 paginator pages created
2 categories created
in 54 ms
Serving pages from /Users/tony/GuoGuoBlog/hugo_gh_blog/public
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

打开浏览器,输入localhost:1313。不出意外,你就可以看到类似下面的站点:

img{512x368}

3、创建github page repository

默认情况,github账号xxxx对应的github page repository是xxxx.github.io。于是我在女儿的github账号下创建public repository:baisibei.github.io。

接下来,我们需要将上步中生成的静态页面push到baisibei.github.io这个repository中。在本地进入到hugo_gh_blog/public目录下,执行:

$git init
$git add -A
$git commit -m"initial commit" .
$git remote add origin https//github.com/baisibei.github.io.git
$git push -u origin master

如果你是用自己的github账号替孩子提交,那么请在该repository下设置collaborator。

push一旦成功后,你就可以直接访问:https://xxxx.github.io查看站点页面了。我这里要访问的是baisibei.github.io。

4、样式问题

问题出现了。在本地样式良好的首页,一旦push到github page上,再用浏览器(chrome)打开,我发现样式全部丢失了,首页被render为“全文字”版本。我一开始怀疑css文件路径不对或无法访问到某个css文件,通过“显示网页源代码”,单独试着访问所有css文件,发现这些文件都是可访问的。还有一个现象是:通过mac safari浏览器、手机上的ucweb、微信内置浏览器浏览,均没有样式问题,显示一切正常(Firefox、IE也均有问题)。将hugo_gh_blog放在我的VPS上,并用hugo作为web server,任何浏览器访问都是没有问题的。

针对这个问题,谷歌和度娘了半天,也没有解决掉。于是我有了换工具的想法。在搜索其他工具资料的过程中,我发现了基于hexo的maupassant theme!没错,就是那个和我目前博客同源的主题:maupassant。这个主题采用响应式的设计,对不同屏幕的访问均有很好的适配。

之前我的博客为了适应智能终端的浏览,采用了WPtouch插件,效果差强人意。这次我特地停用了该插件,直接用手机访问我的博客,发现maupassant的显示效果是棒棒的。于是下一步,我将hugo更换为hexo,主题由Lanyon更换为maupassant。

hugo_gh_blog和baisibei.github.io依然保留在github.com上,后者的名字被rename为baisibei.github.io.using.hugo。

三、基于hexo搭建博客站点

1、安装hexo相关工具

第一次用hexo,安装hexo过程需要一些耐心:

$npm install hexo-cli -g
{耐心的等待... ...}

$which hexo
/usr/local/bin/hexo

$hexo -v
hexo-cli: 1.0.2
os: Darwin 13.1.0 darwin x64
http_parser: 2.7.0
node: 6.9.1
v8: 5.1.281.84
uv: 1.9.1
zlib: 1.2.8
ares: 1.10.1-DEV
icu: 57.1
modules: 48
openssl: 1.0.2j

2、创建blog

使用hexo init在本地创建blog repository目录:

$hexo init hexo_gh_blog
{耐心等待...}
... ...
INFO  Start blogging with Hexo!

进入hexo_gh_blog目录:

$cd hexo_gh_blog
$ls
_config.yml    node_modules/    package.json    scaffolds/    source/        themes/

没完,我们还需要install一下相关的依赖:

$npm install
{耐心等待....}

通过”hexo g”命令生成blog文件:

$hexo g
INFO  Start processing
INFO  Files loaded in 270 ms
INFO  Generated: index.html
INFO  Generated: archives/index.html
INFO  Generated: fancybox/blank.gif
INFO  Generated: fancybox/jquery.fancybox.css
INFO  Generated: fancybox/fancybox_sprite.png
INFO  Generated: fancybox/fancybox_loading.gif
INFO  Generated: fancybox/fancybox_overlay.png
INFO  Generated: fancybox/fancybox_loading@2x.gif
INFO  Generated: fancybox/jquery.fancybox.pack.js
INFO  Generated: fancybox/jquery.fancybox.js
INFO  Generated: fancybox/fancybox_sprite@2x.png
INFO  Generated: archives/2016/12/index.html
INFO  Generated: css/fonts/fontawesome-webfont.eot
INFO  Generated: css/fonts/fontawesome-webfont.svg
INFO  Generated: css/style.css
INFO  Generated: css/fonts/fontawesome-webfont.ttf
INFO  Generated: fancybox/helpers/fancybox_buttons.png
INFO  Generated: css/fonts/FontAwesome.otf
INFO  Generated: js/script.js
INFO  Generated: fancybox/helpers/jquery.fancybox-buttons.css
INFO  Generated: archives/2016/index.html
INFO  Generated: css/fonts/fontawesome-webfont.woff
INFO  Generated: fancybox/helpers/jquery.fancybox-media.js
INFO  Generated: fancybox/helpers/jquery.fancybox-buttons.js
INFO  Generated: fancybox/helpers/jquery.fancybox-thumbs.css
INFO  Generated: fancybox/helpers/jquery.fancybox-thumbs.js
INFO  Generated: css/images/banner.jpg
INFO  Generated: 2016/12/16/hello-world/index.html
INFO  28 files generated in 867 ms

$ls
_config.yml    db.json        node_modules/    package.json    public/        scaffolds/    source/        themes/

和hugo命令类似,hexo g也创建了public目录,并将站点的静态文件生成在这个目录下面。

通过hexo s可以启动一个web server,在本地查看生成的静态站点:

$hexo s
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/. Press Ctrl+C to st

hexo自带的landscape theme真的是不咋好看。

3、更换主题为maupassant

先清理一下生成文件,再clone maupassant主题:

$hexo clean
INFO  Deleted database.
INFO  Deleted public folder.

$git clone https://github.com/tufu9441/maupassant-hexo themes/maupassant
Cloning into 'themes/maupassant'...
remote: Counting objects: 1310, done.
remote: Total 1310 (delta 0), reused 0 (delta 0), pack-reused 1309
Receiving objects: 100% (1310/1310), 562.88 KiB | 382.00 KiB/s, done.
Resolving deltas: 100% (747/747), done.
Checking connectivity... done.

$ls themes/
landscape/    maupassant/

编辑hexo_gh_blog/_config.yml文件,修改theme为:maupassant

//_config.xml
theme: landscape

=>

theme: maupassant

重新生成站点静态文件之前,我们还需要安装下面两个工具,否则hexo生成出来的静态页面也是不可用的:

$ npm install hexo-renderer-jade --save
$ npm install hexo-renderer-sass --save

hexo g和hexo s后,你就可以在本地:localhost:4000地址上看到生成的静态页面了:

img{512x368}

仿效上面章节中的步骤,将public目录push到baisibei.github.io repository中,看看我们上传后的站点通过公网访问是否还有“失真”现象,结果:一切正常。

4、定制站点

a) 定制hexo_gh_blog/_config.yml

这个_config.xml中的配置都是站点全局范畴的,这里仅我将我修改过的一些定制属性贴出来:

# Site
title: Amy Bai
subtitle: 果果的成长历程
description: 记录一个小女孩儿在学习、生活、家庭、情感方面的成长经历
author: Amy Bai
language: zh-CN
timezone: Asia/Shanghai
since: 2016
avatar: https://avatars0.githubusercontent.com/u/24524343?v=3&s=400

# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: http://daughter.tonybai.com

默认情况下,maupassant主题的menu中包含rss菜单项(站点的订阅feed),对应的访问路径是/atom.xml,但要生成atom.xml,需要安装另外两个plugins:hexo-generator-feed和hexo-generator-sitemap:

在_config.xml中添加:

plugins:
- hexo-generator-feed
- hexo-generator-sitemap

安装这两个插件;

$npm install hexo-generator-feed --save
hexo-site@0.0.0 /Users/tony/GuoGuoblog/hexo_gh_blog
└── hexo-generator-feed@1.2.0

$npm install hexo-generator-sitemap --save
hexo-site@0.0.0 /Users/tony/GuoGuoblog/hexo_gh_blog
└── hexo-generator-sitemap@1.1.2

安装后,执行hexo g,会看到atom.xml的生成。不过由于hexo版本似乎与feed插件有兼容性问题,当执行hexo s时,命令报错。我暂时在_config.xml中先注释掉这两个插件,待后期看是否能解决,不过这不影响站点的主要功能。

b) about页面

在maupassant主题的menu中默认还包含了about菜单项,但在生成的站点静态页面中点击about菜单项,将返回失败页面。如何给站点添加about页面呢?

在hexo_gh_blog/source下创建about目录,进入about目录,创建index.md文件,内容诸如:

---
title: 关于我
---
我是Amy Bai,小名果果。

这样hexo g和hexo s后,你就有about页面可供访问了。

5、写post

hexo通过hexo new 命令来创建一篇post,我更喜欢简单粗暴,直接再hexo_gh_blog/source/_post创建一个xxx.md文件,这就是一篇post。post内的markdown格式和很多工具都是类似的:

以initial-post.md为例:
---
title: "第一篇(待写)"
date: "2016-12-15"
description: "第一篇博文,敬请期待^O^"
categories:
    - "日记"
    - "感悟"
---

## 标题一

第一篇文章,敬请期待

### 子标题

## 小结

^O^

hexo按md文件头中的date对post进行排序。title就是显示在文章中的标题。description是文章摘要。默认情况下,maupassant主题在首页只是展示文章摘要而不是全文。

四、域名绑定

还没有申请顶级域名下的二级域名,目前打算绑定daughter.tonybai.com这个子域名。怎么做呢?

在public目录下,创建CNAME文件,文件内容:daughter.tonybai.com。然后将文件Push到github上去。

在你的域名管理站点,创建”daughter.tonybai.com”子域名,并将其CNAME值设置为”baisibei.github.io”。生效后,打开浏览器,访问”daughter.tonybai.com”,你就可以看到你刚刚生成的新站点了。

五、小结

站点搭建好了!用各种终端访问,感觉效果还不错。post发布也很方便,如果你想自动发布,定义一下hexo deploy即可。我个人习惯手动提交,也就没这个步骤了。

接下来,把内容创作的任务就交给果果了^_^。

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! 图片广告位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