Ampio知识库
help.ampio.com我们是 Ampio。 我们设计和制造楼宇自动化系统,提供控制、舒适、安全和可靠性。访问 我们的页面 了解更多关于我们解决方案的信息!
Ampio 知识库 是一个使用 Hugo 构建和维护的服务。它是我们客户和认证安装人员的自助服务支持平台。它还包含我们模块的完整产品组合——Ampio 楼宇自动化系统的构建块。
网站由以下人员构建:
- @mgetka ,开发者
- @SteynAnna ,维护者
以及负责内容创作的其他 Ampio 团队成员。

作为一家专门为各个行业提供高度可定制智能解决方案的公司,Ampio多年来积累了大量的知识。我们一直在寻找一个用户友好的平台,以便将这些知识传授给我们的客户和安装人员。为遍布全球、需求和期望差异巨大的两个受众群体提供服务是一项挑战。
一方面,我们需要一些东西能够以一种视觉上吸引人的方式向没有技术知识的客户讲解我们的系统。
另一方面,我们的安装人员需要技术图纸、离线手册以及对高度专业化主题的深入了解。
最重要的是,我们不能忽视这样一个事实:我们内部的知识库编辑和维护团队包括非程序员,他们必须能够像那些擅长编码的人一样创建内容并浏览网站的架构。
我们从以下需求开始:
- 易于贡献
- 高效的搜索功能
- 可部署到简单的共享主机
- 对多语言的支持
WordPress的黑暗时代
考虑到以上几点,我们使用商业知识库插件在WordPress中构建了服务的第一个版本。最初的需求似乎并不过分,然而我们惊讶地发现,只有少数几个可用的解决方案涵盖了这些需求。特别是,多语言的情况在现有产品中似乎特别被忽视。
基于WordPress的产品做出了很大的承诺:支付一些费用,几分钟内启动服务,忘记所有开发麻烦。虽然这些承诺可能在WordPress端是可以实现的,但对于最通用的部署来说肯定不是真的。在我们的案例中,我们面临着越来越多的权衡。此外,该解决方案在我们专门用于这项工作的简单共享主机环境中运行速度很慢。
转折点
转折点是引入了新的关键需求——每个文档都必须能够以PDF格式下载。我们拥有的插件中没有这种功能,而且看起来也没有其他现有的WordPress插件能够令人满意地满足我们的需求。我们团队中没有人勇敢到足以将这样的功能添加到当前的堆栈中,所以我们决定从头开始。
除了新的开发之外,我们还必须记住我们的另一个关键需求,即大部分非程序员将负责服务的维护和内容创建。最初,我们倾向于基于无头CMS的解决方案,但最终我们大胆地决定创建一个Git管理的Jamstack服务,看看会发生什么。
Hugo来救援
Hugo是我们首选的SSG。多语言支持是说服我们的主要功能。后来,在阅读文档的过程中,我们继续发现了一些新的令人兴奋的功能,这些功能在我们开始时甚至都不知道我们需要。
WordPress所见即所得编辑器的丰富功能很快变成了一个诅咒。维护由多个贡献者准备的文档的格式一致性变得很繁琐。当我们考虑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是最好的!如果你曾经面临类似的挑战,一定要尝试一下。如果你的服务贡献者技术水平不高,也不要三思而后行——它仍然可能取得成功!
Improve this page