标签 github 下的文章

基于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语言联合作者Rob Pike专访:Go确实已成为云基础架构的语言

尽管看到Docker,Kubernetes和用Go编写的云计算的许多其他组件令人欣喜和重要,但也许并不奇怪。Go确实已经成为云基础架构的语言。- Rob Pike,Go编程语言的联合作者

本文翻译自《Rob Pike interview: “Go has indeed become the language of cloud infrastructure”》

img{512x368}

简介

我们与Go编程语言之父Rob Pike(以下称Rob)谈谈跨越整整40年的职业生涯、过去10年来Go语言的变化,以及未来Go语言的演化方向。

专访

Evrone:您与今天的许多开发人员不同,您数十年前就在Bell Labs开始了您的职业生涯。以您的阅历和认知,您认为我们开发软件时最大变化是什么?

Rob:今天的软件规模(scale)更大。不仅是计算机和网络,还有程序本身。所有Unix版本6(大约1975年)的程序都可以顺利地安装在单个RK05磁盘包上,该磁盘包的存储量刚刚超过2MB,还为用户软件留出了很大的空间。那是一个很好的计算环境,或者至少在当时看起来是一个。当然,尽管我可以解释其中的大部分增长,但令人惊讶的是,也许并不是所有的增长都是合理的。

Evrone:鉴于“变革的阻力”和“兼容性的承诺”,您如何看待Go编程语言及其生态系统在未来十年的发展?您认为的该技术的最佳未来是什么呢?

Rob:尽管还不确定,但经过十多年的努力,一个看起来更像是针对参数多态性的设计即我们俗称泛型(具有误导性)的东西将在未来一两年内问世。找到一个可以在现有语言中运行并且感觉好像属于它的设计是一个非常困难的问题,但是伊恩·泰勒(Ian Taylor)在该问题中投入了巨大的精力,看来现在已经找到了答案。我也非常渴望看到该设计会如何影响库、生态系统和社区的。

Evrone:随着“渐进类型”引入“动态类型”语言以及“类型推断”引入“静态类型”,两者之间的界限现在变得越来越模糊。您对现代编程语言的类型系统有何看法?

Rob:我非常喜欢静态类型,因为它带来了稳定性和安全性。

我也非常喜欢动态打类型,因为它带来的乐趣和轻巧的感觉。

我不喜欢类型驱动的编程、类型层次结构、类以及继承。尽管已经通过这些方式构建了许多非常成功的项目,但我认为这种方法将重要的决策过早地推到了设计阶段,而经验并没有影响到它。换句话说,我更喜欢组合而不是继承。

但是,我对那些喜欢使用继承来构造程序的人说:不必在意我的观点,请继续使用对你们有用的东西。

Evrone:有时候人们以奇怪的方式使用技术。例如,要从高级PythonRuby代码生成高效的Go代码(是的,我们已经看到了!)多年来,您看到过最奇怪,最有创意或有趣的Go用法了吗?最让您惊讶的是什么?

Rob:最大的惊喜是当我们得知Go被用于编写恶意软件时(译注:手动允悲)。您无法控制谁将使用您的作品或他们将如何使用它。

Evrone:您设计和实现了许多文本编辑器。您如何看待Visual Studio Code?通过LSP之类的技术,“文本编辑器”和IDE之间的界限现在变得模糊了。您是否认为软件开发人员需要功能强大的IDE(如GoLand)或使用VSCode很好?

Rob:我来自IDE之前的时代。但是在项目的早期,有人谈到Go是否需要IDE才能成功。但是,团队中没有人拥有这方面的技能,因此我们没有尝试去创建一个(Go专属IDE)。但是,我们确实创建了用于解析和打印Go代码的核心库,这为各种编辑器和IDE快速创建了高质量的插件提供了极大的便利,这也算是一个偶然的成功。

最近,我们一直在努力为Go开发LSP服务器,该服务器称为gopls,支持该协议的任何编辑器或IDE均可使用该服务器,以改善使用该语言的体验。

也许是因为我们对使用简单的编辑器形式感到满意,所以我们确保大家无需背负沉重的编程环境搭建负担即可轻松地使用Go工作。但是,IDE当然可以提供帮助:我今天看到的大多数使用Go IDE或至少使用具有自定义Go支持的编辑器的开发人员都能从中获得很多价值。

使用哪种编辑器风格的问题取决于您的口味,并随您所用语言的文化而变化。

Evrone:软件开发人员倾向于给事物打标签,例如Dart是一种“前端语言”,而C是一种“系统底层语言”,等等。就目前的Go语言的功能集和用法,您现在如何称呼它?

Rob: Go是一种通用编程语言。编写您想要的任何内容,不必担心将语言或与此相关的任何其他技术固定到单个问题域。

Evrone:您个人还喜欢哪些其他现代编程语言?

Rob:Go的经验告诉我,人们喜欢对语言发表意见,这可能比我们领域中的几乎任何其他要素都要多。我当然也是这样做的。但是我对经常导致的消极情绪感到厌倦,所以现在我尽量避免评判那些事情。

在很少有新的语言问世并获得成功的一段时间之后,在过去的十多年中,语言设计才有了真正的复兴。很高兴看到这一点及其带来的创新。

Evrone:成为Google员工是如何帮助您开发和引导Go语言的?能够在Twitter上问“告诉我们您如何使用我们的语言”并获得全球最大公司的回应有多重要?它只是语言开发的一个不错的补充还是必不可少的一部分?Google如何为您提供帮助的?

Rob: Google非常支持Go项目,对此我深表感谢。当然,创建该语言是因为我们认为Google需要它。所谓的“云计算”需要一种具有对并发性和易于部署等方面良好支持的语言。但是Google并没有以任何重要方式指导该项目。它支持我们,让我们做我们认为最好的事情。

对于其他公司和其他用户,社区的投入对于理解项目的进展至关重要,我的意思是语言,编译器,工具,运行时,库,环境(所有这些)的发展。

Evrone:经过10年的Go开发以及对其使用方式的观察,您能说出该语言最大的设计成功和最大的失败是什么?分别是最强点和最弱点?

Rob:我要说两件事,一是技术问题,一是政治问题。

技术上是对并发计算的原生(first-class)支持。Go仅仅存在了十年左右,但是当它被开发时,“线程”和并发在编程社区中并未得到广泛认可。实际上,创建Go的主要原因是当时很难用C++进行并发计算。并发支持在发布后不久就很明显成为了该语言的一个主要吸引力,可以弥补一些人认为该语言其他部分的缺点。并发动了大家的神经。一旦人们开始使用并发功能,他们便开始探索有关该语言的其他内容,并发现那里(Go语言中)存在的东西超出了他们最初的想象。支持并发是(进入Go语言世界)的网关。

正如CloudflareJohn Graham-Cumming所说:“我为实现简单的并发而来,而为实现简单的组合而留下来”

Go改变了有关如何对多核计算机进行编程的讨论。

Go语言在政治上的成功是坚定的执行了关于Go1兼容性的承诺。曾经我们和社区一旦使用Go几年,我们就有了很长的清单需要修复,但是变化是破坏性的。因此,我们仔细设计了更新程序,并使用了“go fix”命令来推动社区发展。完成这些后,我们不仅停了下来,而且还承诺会保持这种“停止”状态。这种稳定性 – 2012年编写的Go程序今天仍可以编译并完美运行 – 是促进增长的巨大推动力。公司可以放心使用我们,因为我们不会破坏其软件。在Go 1.0版本及其兼容性承诺出现之后,Go的采用率急剧上升。而且,从那以后,尽管我们有许多我们想改变的东西,但是我们不能破坏现有的程序,对此,我们感觉很好。

Evrone:您的工作与生活平衡如何?现在有很多关于“倦怠”的话题,这种流行病根本没有帮助。以你40年的阅历,您对新一代开发者有何提醒?

Rob:避免倦怠的最佳方法是在支持您的环境中做自己真正喜欢的事情。在整个职业生涯中,我一直很幸运,但是我意识到并不是每个人都如此幸运。如果您因工作而感到压力,则应随时休息或改变方向,尤其是在当前情况下。

Evrone:事后看来,许多技术的普及归功于使它们流行的所谓“杀手级应用”。您能为Go编程语言列举出这样的“杀手级应用程序”吗?您整体上对这种“杀手级应用程序”想法有何看法?

Rob:几年前,Danny Berkholz将Go称为“云基础架构的新兴语言”,这绝非偶然。Go是由Google的工作人员设计的,目的是使编写与Google相关的软件(特别是驻留在网络中的服务器)更容易。就是今天我们所说的“云”。(该设计的某些动机是在我2012年的Splash主题演讲: Go at Google: 软件工程服务中的语言设计

因此,尽管看到用Go语言编写的DockerKubernetes和云计算的许多其他组件很令人高兴且很重要,但也许并不奇怪。Go确实已经成为云基础架构的语言

Evrone:您觉得Go语言的竞争对手是谁?在哪个领域竞争?您对Rust的“无垃圾收集”构想和编译时保证有何看法?

Rob: Rust是一种有趣的语言,我很感兴趣地看着它的发展。除此之外,正如我上面所说,我没有意见。

Evrone:Go在GitHub上已达到7万颗星!您如何看待GitHub,Reddit,Twitter,离线和在线会议,网络研讨会等不同的社交活动对语言的影响?它们对语言的成功重要还是仅仅反映了语言的成功?

Rob:我们通过会议和社交媒体结识的人们一直是Go及其所有元素发展的关键部分。许多许多贡献者以积极的方式影响了开发,包括将Go移植到Windows和许多非x86架构上,工具和库的开发,对技术建议的深入讨论等等。

反过来,Go团队也与社区进行联系并积极讨论,提出问题并寻求帮助和指导。

我认为重要的一件事是,以一种声音与社区互动,以团队而非个人的身份说话。一致的消息更容易理解。

Evrone:成为一种流行的编程语言的作者如何改变了您的生活?

Rob:一个更正:我是合著者,而不是作者。肯·汤普森(Ken Thompson)和罗伯特·格里塞梅尔(Robert Griesemer)与我一起开始了这个项目,其他许多人也做出了巨大贡献。因此,请不要单把我列为“作者”。

为了回答您的问题,Go无疑提高了我的公众形象,并向我介绍了一个新的充满活力的社区,但是除此之外,它并没有太大的作用。我有很长的职业生涯,并取得了其他的成功(以及无数的失败)。

Evrone:想象一下,如果您有机会时光倒流并且给年轻时候的你提出一个建议(只有一个),如果是回到大约在您开始设计Go语言规范时,您会给您自己和您的同事提出什么建议?

Rob:很简单:忽略仇恨者(haters)。只倾听那些能理解和分享您目标的声音;他们是在乎Go的人。并非每个人都认同您在做的事情,这没关系。但是,那些致力于推进您想要做的事情的人可能会成为想法,能量和灵感的绝佳来源。

我们将永远感谢我们充满热情的社区。


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

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

2020年4月8日,中国三大电信运营商联合发布《5G消息白皮书》,51短信平台也会全新升级到“51商用消息平台”,全面支持5G RCS消息。

著名云主机服务厂商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