大概是在2019年的时候，我折腾过gitbook。

当时分别用它的两种主题做了两个小玩意儿，一个是默认主题“theme-default”，它就是最基本的“book”样式，我用它来做Spring Boot文档的翻译，而且还针对它的样式做了一些自定义，让它看起来更像Spring官网的样式。另一个用到的主题是：“theme-faq”，用它做了一个快速查询的静态网站，关于这个项目我在“readme.md”中是这么写的：“主要放一些没那么常用、真用的时候又想不起来的一些东西”，内容主要是各种命令：Linux的命令、git命令、nodeJS命令等，页面中间是个大搜索框，搭配gitbook当时优秀的插件生态装上支持汉字搜索的插件，还算用的挺好。

因为各种原因，这两个项目在后来的一段时间没有维护。今年在折腾完hugo后，又想折腾这一块了，发现从2018年之后本地版的gitbook已经停止更新了，官方不再维护。所以，我才准备要找其替代者来重新实现当年的这两个小玩意儿。

在写本篇文章的时候，我想重新装上gitbook，然后截几张图放上来。结果发现好麻烦，安装失败，原因好像是我本地的npm版本过高，只能算了，不值得再折腾它了。

只有契合需求、解决痛点的解决方案才是好的解决方案，所以先明确一下我们的需求：

  1. 要是一款静态网页生成器，支持Markdown
  2. 支持搜索
  3. 尽量简单

带着这些需求，我开始了寻找gitbook替代者之路。

1. 最简单之选：mdBook

mdBook是采用Rust语言做的，非常的轻量化，配置和使用起来都非常的简单，而且无论是从使用习惯和页面风格上都与gitbook极为类似。

效果如下：

mdBook的优势：

  1. 极容易上手，配置也非常简单
  2. 支持在线编辑、执行Rust代码（必杀技，其他任何“竞争者”都不具备这个特性）

mdBook的劣势：

  1. 生态太差，很难搜到问题的解决方案，也几乎没有可替换的主题（可能是我不会玩）
  2. 自带的搜索不好用，且不说汉字搜索了，搜索英文也存在问题，例如文章中出现过“Redis”，而使用“edi”就搜索不到。（也同样怀疑是我没玩明白）

其实，我是非常想用mdBook来做我们上面提到的那个“命令快速查询”项目的，因为我太喜欢这个简介明了的feel了。但是“命令快速查询”核心是搜索，现在搜索玩不明白自然也就被一票否决了。

2. 均衡之选：hugo + hugo-book

hugo大家应该清楚，它有一个主题“hugo-book”，该主题追求简单、甚至“0配置”，目前在GitHub上的点赞数有1.3k。

我在折腾它的时候，确实感到配置可以很少，而且与mdBook相比它可配置的内容更多、可定制化更强。最终，我选定使用该主题来做Spring文档的翻译，生成的静态文件托管在GitHub上，使用GitHub Pages对外提供Web服务，可点击查看效果：https://hongmao.run/spring-doc/。

hugo + hugo-book的优势：

  1. 均衡，既简单又有一定的定制化空间（论轻量级比不过mdBook）

hugo + hugo-book的劣势：

  1. 搜索同样不好用

3. 高级选项：hugo + Docsy

hugo有一个主题：“Docsy”，它是谷歌开源的一款主题，目前在GitHub上的点赞数有1.3k。

来头很大，而且确实很高级，但是我感觉下来，它却不是我那两个项目的优秀解决方案。所以，我也没有很细致的去折腾它，总体来说，水很深，我把握不住。它应该更适合于去介绍一个成熟的产品，既包含了博客模块也包含了文档模块。

hugo + docsy的优势：

  1. 功能强大，可配置项众多
  2. 文档极为完善，也提供了demo项目（如果没有这两样，真的是很难玩转）

hugo + docsy的劣势：

  1. 搜索问题同样存在（我真的开始怀疑是我的问题了）
  2. 配置复杂，上手难度高

4. 意外之喜：hugo + geekdoc

在浏览hugo的众多主题时，发现了一个意外之喜：“geekdoc”主题。

但是，其实我并不是用它来实现我的那两个项目的，而是发现它可以用来做我的另一个项目。我之前在阅读jdk中的源码，源码的阅读笔记直接写在博客中。在倒腾这个主题的时候，我突然发现，很适合用它来做一个“源码阅读笔记”啊。这里面有个很重要的原因，它支持在菜单前添加svg图标，因为我之前的此类源码阅读笔记草稿是记录在我的Notion笔记中的，在Notion中的效果如下：

图标是用的IDEA中的（他们公司的人说可以使用），用于区分出类、接口、抽象类和包。

最终，我的JDK8源码源码阅读笔记：https://hongmao.run/jdk8-src-note/

hugo + geekdoc的优势：

  1. 文档完善，上手难度不高
  2. 配置丰富，具备可定制化空间
  3. 作者具备极客精神，有问题时响应较快且更新迭代的速度也较快

hugo + geekdoc的劣势：

  1. 目前尚处于成长期，存在一些问题还需完善
  2. 同样存在搜索的问题（不提一嘴的话，我怕大家会以为它的搜索没有问题）