Hi,

Seems that with Spring Boot 3.3.0 you have removed the single page variant of the reference documentation, as it now redirects to https://docs.spring.io/spring-boot/index.html. Please restore it, it's necessary for

  1. fast cross referencing across the entire framework and
  2. finding things which one can't remember exact names/keywords for

The segmented reference at https://docs.spring.io/spring-boot/index.html is useful only if one already knows the general structure of the whole documentation, which really doesn't apply to a casual reader since Boot is a massive project.

Comment From: wilkinsona

Thanks for the feedback.

fast cross referencing across the entire framework

Spring Boot 3.3 has moved to Antora for its documentation, aligning with various other projects that have already moved over the past several months. One of the main benefits of Antora is that you can now search across the entire Spring portfolio from Spring Boot's documentation. You can access this search at https://docs.spring.io/spring-boot/search.html or by clicking in the search box on the left-hand side and then selecting Search in all Spring docs.

finding things which one can't remember exact names/keywords for

Can you please describe how would you do this with the single-page documentation?

Comment From: esuomi

Spring Boot 3.3 has moved to Antora for its documentation, aligning with various other projects that have already moved over the past several months.

To be blunt, in all honesty I don't like this move at all :) It's all too granular.

Can you please describe how would you do this with the single-page documentation?

As a recent example, lets say I'm interested in learning more about how to do custom health checks for actuator.

  1. From googling, I learned that the relevant class is HealthIndicator. I also learned about liveness and readiness.
  2. In the documentation I would use a mix of terms - name of the relevant class, related keywords such as "custom health", and some side keywords such as "readiness" and "liveness" to understand where in the document all of these are referenced and how they relate to each other.

To be clear, it's not just about finding the correct snippets and sections of the documentation, but also about seeing their relative proximity and order as well. No documentation is perfect, and it's very easy to forget to do cross-references, so Ctrl/Cmd+F:ing the full document gets around that nicely, without losing the spot at where I was in general in the documentation. If my various keywords all point to hotspots at around, say 2/5ths mark of the page and towards the last quarter, it means the relevant related sections for understanding how everything meshes together are around those parts. For me this exploration and overview is quite important for any documentation.

And while I don't personally rank these that high, there are some other secondary benefits to single-page docs as well, including printing, reader mode support, reduced network bandwidth usage, and whatever else others may enjoy.

Comment From: wilkinsona

reduced network bandwidth usage

I think this is an area where the new documentation excels. https://docs.spring.io/spring-boot/docs/3.2.x/reference/htmlsingle/index.html weighs in at 470KB where as each individual page of the new docs has HTML in the 10KB - 20KB range. This also shows in the rendering time with the single page docs taking almost 8 seconds according to the timeline in Safari vs 3 seconds for a page of the Antora-based docs.

We don't consider the current docs to be finished, documentation almost never is, and that's especially true here as this is the first iteration of them with the new Antora-based structure. As such, I expect things to evolve based on feedback such as this. For example, the point about cross-references in a good one and I suspect that we'll want to add many more now that the pages are more fine-grained. We should make sure that we keep this in mind when tackling https://github.com/spring-projects/spring-boot/issues/40064.

One thing that I think I can say with some certainty is that we won't be going back to the old documentation structure instead of the Antora-based docs. Assuming that Antora supports it, what we can consider is also publishing single-page documentation either as HTML or perhaps as a PDF. Right now, though, my preference would be to continue to evolve and improve the documentation in its new format as there are some significant advantages to not publishing the same content in multiple formats, not least search engine discoverability which has hampered our docs for years.

Comment From: philwebb

There is an effort underway in the Antora community to address the "single page documentation" requirement. I think it's mostly focused on PDF generation at the moment.

I would very much like to be able to publish some aggregated form of our documentation. I think a lot of folks would like to be able to download something that they can read offline.

I'll repurpose this issue to look into that, but it's something we'll likely want to tackle as broader team to that all projects can benefit. As such, I suspect it may take a little time.

I wish we had a simple switch we could throw that would allow us to restore the single page HTML generator. Unfortunately, it's not that easy and we don't have the bandwidth to maintain two distinct sets of .adoc files.

Comment From: petenattress

I just want to say I completely agree with all @esuomi's points. The single page HTML version of the documentation was incredibly useful to me when I was learning Spring/Spring Boot as it wasn't always obvious which section would contain the information I needed so searching with Ctrl+F and quickly scanning through became invaluable. This is especially true where the boundaries between Spring Framework, Spring Boot, Spring Data etc are a bit fuzzy - I would just have three tabs open with the three full pages and search through each to find the info I needed.

For those who are already familiar with the structure of the Spring projects and documentation I think the new Antora version is fine, but if I was coming freshly into Spring I honestly think I would struggle to use it as efficiently as I was able to use the single HTML pages. The Antora search function seems quite limited to me and there doesn't seem to be much rhyme or reason behind the order it displays results in.

The Spring documentation is generally very high quality, which is obviously important for a project of this size and complexity. It would be great to see a restoration of the single page HTML/PDF version of the docs so the usability of this valuable resource isn't impaired.

Comment From: jeanjerome

Not to mention that a single documentation page can easily feed an LLM using RAG, which can be an advantage in current times, especially when aiming to dive into new technologies like Spring AI 😬

Comment From: GithubUser8080

Agreed, single page was the only viable documentation for me, the current system does not work without internet, is not transferrable and you cannot use CTRL + F to easily search

Comment From: kllmanu

Another big advantage of the single html file was the ability to create yourself an epub file out of it. One could have used pandoc to do so and read the documentation on an ebook reader.

Comment From: renannprado

I really wish I could look into the documentation during a flight (where I most likely won't have Internet), even if it's exactly the same as the one provided online, but without the algolia search. Is it possible to just get a zip with all the HTML pages so that I can browse offline?

Comment From: philwebb

@renannprado If you don't mind building it yourself you should be able to checkout this repository and do ./gradlew antora then take the contents from spring-boot-project/spring-boot-docs/build/site.

Comment From: Crain-32

Hey @philwebb,

It appears there is an official alpha PDF Extension for Antora. While I understand not wanting to use an alpha version of software it does appear that the desire for an aggregate/pdf version of the documentation exists. I'd attempt the changes myself, but based on the comment,

The docs-build is internal to the team for our doc generation process. I am afraid it's not part of Spring Boot OSS and we don't provide support for it.

in #43634 I'm unsure if I got it working locally the solution would be applicable. Let me know if that isn't the case and I can try it out.

Comment From: rob-valor

Also, in line of what @jeanjerome mentions, when bundling all the Spring (boot, framework, cloud...) PDF documentation into a single notebook (https://notebooklm.google.com) it's really easy to find an up-to-date and correct answer to specific questions. That's also because a lot is really good documented. So being able to use that documentation in modern tools, makes it even better 😉

Comment From: spirosag

I won’t reiterate the benefits of single-page HTML/PDF documentation—others have already covered that earlier in this thread, and I completely agree with them. From a maintainer’s perspective, I understand that the new Antora-based docs might be easier to manage. However, from a usability and user experience standpoint, it is unfortunately much worse.

This isn't just my personal opinion—it's the consistent feedback I’m getting at work. In fact, I’ve seen colleagues revert to the last available single-page documentation because searching in the new docs is significantly more difficult.

I get the impression that the maintainers aren’t fully convinced that this is an important use case. At this point, I’m almost tempted to write a script that scrapes Antora docs into a single-page Markdown format and call it a day. 😢

Comment From: rwinch

Thanks for the feedback everyone. I'm sorry that the documentation changes have caused you problems.

There are a lot of concerns and solutions proposed on this ticket. Since these are portfolio wide concern and not Spring Boot specific, I'd propose that everyone provide feedback in a more centralized place. Unfortunately, the building blocks for how the documentation is created are scattered around which makes it difficult to identify the correct place to log a ticket. To simplify this a bit, you can create tickets at https://github.com/spring-io/antora-ui-spring/issues and if necessary we can move it to the appropriate place.

I've created https://github.com/spring-io/spring-doc-actions/issues/33 which will result in a zip file of the site that allows for offline usage of the documentation. I know that this does not address all of the concerns that were brought up, so please log additional tickets for additional concerns.

When you log a ticket, please start by providing the problem that you are having (e.g. I cannot view the Spring Docs offline) rather than starting with a solution (please provide an HTML Single version of the documentation). This will help us to understand the problem and work together with you to determine what the best solution is.

Thank you again for your feedback. We look forward to working together with you to address your concerns and improve the Spring Documentation!

Comment From: rwinch

I've added https://github.com/spring-io/antora-ui-spring/issues/275 to track this at the portfolio scope