spring-projects / spring-projects/spring-ai

Provide an official PDF download for the Spring AI reference documentation

Open
#4,659 1 comment 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

status: waiting-for-triage
Dominant language
Java
Stars
9.5k
Forks
2.9k
Avg merge
1d 7h
Merged PRs (30d)
6

Description

Description

The Spring AI reference documentation is currently available only as HTML at
https://docs.spring.io/spring-ai/reference/. Unlike many other Spring projects (Spring Boot, Spring Framework, Spring Data, …) there is no “PDF” button or downloadable spring‑ai‑reference.pdf file.

Why a PDF is needed
  • Offline reading – many developers work in environments without reliable internet access (air‑gapped labs, conference Wi‑Fi, etc.).
  • Print‑friendly – teams often print the docs for quick reference or for internal training.
  • Parity with other Spring projects – a PDF link already exists for Spring Boot, Spring Framework, Spring Data, etc.; having a PDF for Spring AI would keep the documentation experience consistent across the Spring ecosystem.
  • Stable citation – a fixed‑version PDF provides a stable reference for books, blogs and academic papers.
Suggested implementation

The Spring AI docs are written in AsciiDoc (spring-ai-docs/src/main/asciidoc/).

  • Add a Gradle/Maven task (similar to the one used for other Spring projects) that generates spring-ai-reference.pdf from the AsciiDoc sources.
  • Publish the file alongside the HTML docs at
    https://docs.spring.io/spring-ai/reference/pdf/spring-ai-reference.pdf
    (the same URL pattern used by other Spring projects).
  • Update the docs navigation bar to show a small “PDF” link/icon, as done for Spring Boot and Spring Framework.
Affected version(s)

Request applies to the current stable release (e.g. 1.1.x) and all future releases.

Additional context
  • An existing discussion on the absence of PDFs for newer Spring projects can be found in the Spring Framework issue tracker: https://github.com/spring-projects/spring-framework/issues/32907 (PDF version not generated for latest releases).
  • The Spring AI documentation source is already version‑controlled, so generating a PDF is a straightforward add‑on.
Desired outcome
  • A PDF download link that works for every released version of Spring AI.
  • Optionally, the PDF should be included in the Maven Central “spring‑ai‑docs” artifact so users can fetch it with mvn dependency:get -Dartifact=org.springframework.ai:spring-ai-docs:1.1.0:pdf.

Thank you for considering this request!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in spring-ai-docs/src/main/asciidoc/ and inspect how the documentation navigation bar and release publication are configured. Compare the PDF generation and navigation patterns used by Spring Boot and Spring Framework. Done means a spring-ai-reference.pdf is published for every released version, with a working PDF link in the documentation.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.