Ampio知识库

作为一家专门从事高度可定制的智能解决方案的公司，Ampio多年来积累了大量的知识。我们一直在寻找一个用户友好的平台，以向我们的客户和安装人员传授这些知识。为满足分布在全球各地、需求和期望差异巨大的受众，提供适用于两类用户的服务是一个挑战。

一方面，我们需要一种让没有技术知识的客户以视觉上吸引人的方式了解我们的系统的方法。

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

此外，我们还不能忽视这样一个事实，即我们的知识库的内部编辑和维护人员中有非程序员，他们必须能够像擅长编码的人一样创建内容和浏览网站的架构。

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

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

WordPress的黑暗年代

考虑到上述需求，我们首先在WordPress上使用了一个商业知识库插件构建了我们的第一版服务。最初的需求似乎并不过分，然而我们惊讶地发现只有少数可用的解决方案能够满足这些需求。特别是，多语言的情况在现有产品中被特别忽视。

基于WordPress的产品承诺很大：支付一些费用，用几分钟的时间启动服务，就可以忘记所有的开发麻烦。虽然这些承诺可能在WordPress端实现，但对于不仅仅局限于最通用的部署而言，这显然是不真实的。在我们的案例中，我们面临越来越多的取舍。此外，该解决方案在我们专门为该工作准备的简单共享托管环境中的运行速度非常慢。

转折点

转折点是引入了一个新的关键要求——每个文档都可以下载为PDF格式。我们拥有的插件中并没有这样的功能，也没有其他现有的WordPress插件可以满足我们的需求。我们团队中没有人有足够的勇气将这样的功能添加到当前的架构中，因此我们决定从头开始。

除了这个新的开发需求，我们还必须记住我们的另一个关键要求，即大部分非程序员都将负责服务的维护和内容创建工作。最初，我们倾向于基于headless CMS的解决方案，但最后我们做出了大胆的决定，决定创建一个由Git管理的Jamstack服务，看看会发生什么。

Hugo拯救我们！

Hugo是我们选择的第一个静态网站生成器（SSG）。多语言支持是说服我们的主要功能。在继续阅读文档时，我们继续发现一些新的令人兴奋的功能，这些功能在我们开始时甚至都不知道我们需要。

WordPress WYSIWYG编辑器的丰富功能很快就变成了一个问题。在由多个贡献者准备的文档中保持格式一致性变得困难重重。当我们考虑使用Markdown时，我们知道它将给我们带来较少的灵活性。在我们的情况下，它被证明是一个意外的福音——该标记语法强制确保每个文档都以相同的方式准备。而在Markdown不足的情况下，Hugo的shortcodes为我们提供了所需的一切，以获得我们预期的结果。

在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是最好的选择！如果你遇到类似我们的挑战，请务必试一试。如果你的服务贡献者不太懂技术，也不要再考虑了——它可能仍然是个很好的选择！