Spring Framework 6.0.9 参考文档网站更新 | 使用 Antora 提升查阅体验

欢迎加入 Spring cloud 交流群: 617143034

原文地址: https://spring.io/blog/2023/05/11/spring-framework-reference-documentation-update

本博客站点已全量迁移至 DevDengChao 的博客 https://blog.dengchao.fun , 后续的新内容将优先在自建博客站进行发布, 欢迎大家访问.

正文

从 Spring Framework 6.0.9 版本开始，参考文档网站 https://docs.spring.io/spring-framework/reference/ 将使用 Antora 进行生成。

概述

长期以来，Spring Framework 参考文档一直有两个版本，一个是单页的，一个是多页的。
单个页面的文档非常大，但用户可以使用 Ctrl+F 进行搜索。多页面的文档则提供了结构化的内容，但是难以导航和搜索。
例如，参见 4.3.x 版本的单页文档和 多页文档 。

在 5.0 版本中，我们尝试使用单一版本的文档网站，并将文档分成几个章节，作为单页版本和多页版本之间的一种妥协。
您仍然可以在一个章节中使用 Ctrl+F 进行搜索，并且这些页面中任何一页的内容都没有完整文档那么大。
在此版本中，我们还添加了左侧导航，以便轻松浏览内容。请参见 5.3.x 版的示例。

然而，理想情况下的内容应该更加结构化，具有更多独特的 URL，并且易于搜索。
Google 擅长查找内容，但由于同一内容存在多个版本, 并且一些 URL 可能会随着时间的推移而变化，这会导致 Google 难以对文档网站进行索引。因此我们打算集成搜索功能到文档网站中。

然后还有许多类似 Add link to latest current version in the reference manual 这样的问题，即添加从旧版本到最新版本文档的链接。这看起来很简单，但实际需要一个更高级的, 功能更丰富的文档站点，以便它自身可以识别到文档的多个版本。

这就是我们迁移到 Antora 的原因之一。

在过去的几年中，Spring 团队和 Antora 团队合作创建了一个新的文档发布系统，以满足 Spring 项目的需求，包括但不限于上述现代项目文档站点可能需要的功能。

您可以在 https://docs.spring.io/spring-framework/reference/ 看看它的效果。

改进点

首先要注意的是右上角用于选择版本的下拉菜单。

如果您切换到当前版本以外的版本，您会在页面顶部看到一条警告，其中包含指向最新版本的链接。

同样在右上角的搜索框是我个人最喜欢的。

基于 Algolia Docsearch 的集成搜索功能，让您可以搜索整个文档，而无需借助 Google 搜索或加载完整内容以使用 Ctrl+F。

注意： 搜索目前使用默认的 Docsearch UI，它只显示 5 个结果。我们正在积极开发自定义 UI，准备就绪后会切换到它！

在同一区域，您还会看到一个 “编辑此页面” 的按钮，通过该按钮可以轻松提交特定页面的文档更新。

文档内容现在已结构化, 并且分解为了能反映文档结构的唯一的 URL。

左侧是全局导航，主要内容右侧是本地导航，顶部是面包屑导航。

还有很多不太明显的好处。例如，文档更新不依赖于下一个版本发布，而是立即部署到文档网站中。

受影响的 Spring Framework 版本

6.0.x 分支和主分支（当前为 6.1.x）已迁移到由 Antora 生成文档网站, 但我们不打算迁移以前版本的文档网站了 。

现有链接

现有的 6.0.x、6.1.x 和 “当前” 参考文档链接将重定向到具有永久重定向功能的新参考文档。

其他 Spring 项目呢？

Spring Security 已经使用 Antora 一段时间了。
我们也计划迁移其他项目。
我们还计划进一步与 Antora 进行集成，不仅仅跨越同一个项目的不同版本，而且可以跨越不同的 Spring 项目。

更多信息

请继续关注接下来几周的其他博文，其中将更深入地探讨所有这些内容。

推广

欢迎加入 Spring cloud 交流群: 617143034

欢迎大家使用 阿里云优惠券, 新购续费更优惠: