这篇文章已经一年多了,较旧的文章可能包含过时的内容。请检查从发表以来,页面中的信息是否变得不正确。

Docsy 带来更好的 Docs UX

作者: Zach Corleissen,Cloud Native Computing Foundation

编者注:Zach 是 Kubernetes 文档特别兴趣小组(SIG Docs)的主席之一。

我很高兴地宣布 Kubernetes 网站现在采用了 Docsy Hugo 主题

Docsy 主题改进了网站的组织结构和导航性能,并开辟了改进 API 参考的途径。 在 4 年多的时间里,尽管对用户体验方面的改进不多,但 Docsy 针对技术内容实现了一些最佳实践。 该主题使 Kubernetes 网站更易于阅读,并使各个页面更易于导航。 它大大改进了网站所需的外在形象。

例如:添加用于在页面上导航主题的右侧栏。无需再向上滚动导航!

该主题为网站的未来改进开辟了道路。 我最兴奋的 Docsy 功能是主题的 swaggerui shortcode, 它为从 OpenAPI 规范生成 API 引用提供了本地支持。 CNCF 正在与 Google Season of Docs(GSoD)合作,希望在今年第四季度实现更好的 API 参考。 我们很有希望被选中,我们期待着谷歌在 8 月 16 日公布的项目清单。 自从我 2017 年第一次开始使用 SIG Docs 以来,更好的 API 参考一直是我的个人目标。 看到这个目标触手可及,真是令人兴奋。

作为 SIG Docs 的技术负责人之一,Karen Bradshaw 做了很多繁重的工作来解决广泛的网站兼容性问题, 包括在 2018 年我们从 Jekyll 迁移到 Hugo 时修复的最后一个遗留问题。 我们的其他技术负责人,Tim BannisterTaylor Dolezal 提出过很多意见。

还要感谢 Björn-Erik Pedersen,他提供了关于如何在 0.60.0 版本之后进行 Hugo 升级的宝贵建议。

CNCF 与不列颠哥伦比亚省维多利亚市的 Gearbox 签约,将主题应用于该网站。 感谢 Aidan、Troy 和团队其他成员的所有工作!