Ampio 知识库

作为一家专注于为各个行业提供高度可定制智能解决方案的公司，Ampio 多年来积累了大量的知识。我们一直在寻找一个用户友好的平台，将这些知识传授给我们的客户和安装人员。提供一项同时满足全球各地、需求和期望大相径庭的两个受众的服务，是一个挑战。

一方面，我们需要一些东西，让我们能够以一种视觉上吸引人的方式，向对我们的系统没有技术知识的客户进行教育。

另一方面，我们的安装人员需要技术图纸、离线手册以及对高度专业化主题的深入了解。

最重要的是，我们不能忽视这样一个事实：我们的内部编辑和知识库维护团队包括非程序员，他们必须能够像精通编码的人一样创建内容并浏览网站的架构。

我们以以下要求开始了我们的旅程：

• 易于贡献
• 高效的搜索功能
• 可以部署到简单的共享主机
• 对多语言的适当支持

WordPress 的黑暗时代

考虑到上述情况，我们在 WordPress 中使用商业知识库插件构建了该服务的第一个版本。最初的要求似乎并不高，但令我们惊讶的是，只有少数可用的解决方案涵盖了这些要求。特别是，多语言的情况在可用的产品中似乎尤其被忽视。

基于 WordPress 的产品做出了很大的承诺：支付一些费用，在几分钟内引导服务，并忘记所有开发难题。虽然这些承诺可能在 WordPress 端实现，但对于任何比最通用的部署更高级的情况而言，这绝对是不真实的。在我们的案例中，我们正在处理越来越多的权衡。此外，该解决方案在我们专门用于此工作的简单共享主机环境中运行速度很慢。

转折点

转折点是引入了一个新的关键要求——每个文档都必须以 PDF 格式下载。我们拥有的插件中没有这种功能，而且看起来其他任何现有的 WordPress 插件都无法以令人满意的程度满足我们的需求。我们团队中没有人有足够的勇气将这种功能添加到当前堆栈中，因此我们决定从头开始。

除了这项新开发之外，我们还必须记住我们的另一个关键要求，即主要是非程序员负责服务维护和内容创建。最初，我们倾向于基于无头 CMS 的解决方案，但最终我们做出了一个大胆的举动，决定创建一个 Git 管理的 Jamstack 服务，看看会发生什么。

Hugo 来救援

Hugo 是我们 SSG 的首选。多语言支持是说服我们的主要功能。后来，在浏览文档时，我们继续发现新的令人兴奋的功能，这些功能在我们开始时甚至不知道我们需要。

WordPress WYSIWYG 编辑器的丰富功能很快就变成了一个诅咒。维护多个贡献者准备的文档的格式一致性变得很麻烦。当我们考虑 Markdown 时，我们知道它会给我们带来更少的灵活性。在我们的案例中，它被证明是因祸得福——符号强加的约束确保了每个文档都以相同的方式准备。在 Markdown 不够用的情况下，Hugo 短代码为我们提供了实现我们预期结果所需的一切。

在 PDF 生成方面，我们利用自定义输出格式来生成中间文档表示，这些表示由我们的自定义工具使用，将它们转换为 TeX 文档，最终用于生成 PDF 文件。

自定义输出格式也用于创建搜索索引。搜索功能建立在出色的 TNTSearch 库之上。搜索查询和结果由嵌入到 Hugo 处理的静态文档中的 PHP 代码片段处理。

我们甚至实现了由 Hugo 生成的简单 REST API！我们还没有找到任何无法通过此堆栈实现的东西，而在基于 WordPress 的解决方案中，我们在定义类别列表视图中的自定义文档排序等简单的事情上苦苦挣扎。

在谈论 Hugo 时，我们不能忘记速度。起初我们并不认为这是一个杀手锏功能，但随着我们的文档库越来越大，我们越来越欣赏它。空运行并不常见——大多数时候我们都在处理其中一个文档，并且在之前的 Hugo 运行之一中已经构建了缓存。在这种情况下，Hugo 大约在一秒钟内重建站点，我们认为这是一个非常好的结果。

                   | EN  | PL
-------------------+-----+------
  Pages            | 483 | 486
  Paginator pages  |  56 |  55
  Non-page files   | 745 | 749
  Static files     | 917 | 917
  Processed images | 487 | 490
  Aliases          |  80 |  79
  Sitemaps         |   2 |   1
  Cleaned          |   0 |   0

Total in 1096 ms

贡献者之间的适应

很快就变得很明显，我们最初对贡献者之间工作流程适应的担忧被大大夸大了。Markdown 相当简单，并没有给贡献者带来任何麻烦。

我们建议我们的同事使用 Visual Studio Code 作为内容创建工具。该项目的存储库跟踪编辑器项目范围内的配置，其中包括一组允许从 GUI 级别运行实时服务器的任务。这对于那些在面对强大的终端时容易感到害怕的人来说非常有用。

Git 工作流的基本技能也很容易掌握。最后，构建和部署完全由 CI/CD 流程管理，因此服务的管理归结为在 Git 前端查看和接受合并请求。作为副作用，我们收到了完整的清晰的贡献历史记录，这受到了我们的质量保证审核员的赞赏。

我们甚至可以说我们的实验在组织中的非程序员中传播了对 Git 的热爱！

总结

Hugo 是最好的！如果您遇到与我们类似的挑战，请务必尝试一下。如果您的服务贡献者不精通技术，也不要三思而行——它仍然可能会变得很棒！