0012: TREDIS manual PDF

• ID: PRD-0012
• Status: Accepted
• Decision maker: Trevor Gerhardt
• Scope: TREDIS docs app (apps/docs.tredis) and the shared docs shell (packages/docs)
• Product owner: Trevor Gerhardt
• Design owner: Trevor Gerhardt
• Engineering owner: Conveyal
• Last reviewed: 2026-10-16
• Related issues or projects: Not applicable. This work follows a direct request.
• Related designs: Not applicable. The PDF uses the docs site styles.
• Related ADRs: Not applicable. The work uses existing tools and does not cross package boundaries.
• Related user documentation: TREDIS docs README

Summary

The TREDIS docs site publishes the TREDIS 6 User Manual as web pages. Readers can also download the whole manual as one PDF. A maintainer generates the PDF from the same content with one command. The PDF has a cover, a linked list of contents, and every page in navigation order.

User problem and evidence

TREDIS users and clients need the manual as one document. They read it offline, print it, and keep a copy with a project. The original TREDIS help had a print page for this purpose. The new docs site had only separate web pages.

Goals and success measures

Non-goals

• Generating the PDF on request in a Vercel Function. Content changes only on deployment, so a static file is enough.
• Page numbers in the list of contents. PDF bookmarks and links cover this need.
• Chapter titles in page headers.
• A PDF for each chapter or for other docs sites.

Users and use cases

Use case: Read the manual offline

• Actor: TREDIS user
• Need: Download the whole manual from the docs site.
• Goal: Read or print it without an internet connection.

Use case: Hand the manual to a client

• Actor: TREDIS staff
• Need: A complete, dated copy of the manual.
• Goal: Give a client a document that they can keep with a project.

Use case: Publish a content change

• Actor: Docs maintainer
• Need: Change the manual content and deploy it.
• Goal: The downloadable PDF matches the site without extra steps.

Requirements

PRD-0012-US-01: Download the manual as a PDF

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As a TREDIS user, I want to download the whole manual as one PDF, so that I can read it offline or print it.
• Requirement: Every docs page shows a "Download PDF" link in the sidebar. The link downloads the current PDF of the manual.
• Done when:
  • The sidebar footer on each docs page shows "Download PDF".
  • The link downloads tredis-6-user-manual.pdf.

PRD-0012-US-02: Complete manual in navigation order

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As a reader, I want the PDF to contain the same pages as the site in the same order, so that I can find the same content in both.
• Requirement: The PDF starts with a cover and a list of contents. Then it contains each manual page once, in sidebar order. Each page starts on a new sheet.
• Done when:
  • The cover shows the manual title, the generation date, and the source commit.
  • The list of contents shows every page, indented by its level, and each entry links to its page.
  • The PDF contains every page in the navigation, and no page twice.
  • The PDF reader shows the page titles and headings as nested bookmarks.

PRD-0012-US-03: Working links in the PDF

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As a reader, I want links in the PDF to work and to look like links, so that I can follow references.
• Requirement: A link to another manual page goes to that page in the PDF. A link to a heading goes to that heading. A link to a download or other site path goes to https://docs.tredis.net. External links stay the same. Links are visibly different from body text.
• Done when:
  • Selecting a link to another page moves to that page in the PDF.
  • No link in the PDF points to a local or preview server.
  • Links show in the link color with an underline.

PRD-0012-US-04: Compact print layout

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As a reader, I want the PDF to fit a good amount of text on each page, so that the printed manual is not longer than it needs to be.
• Requirement: The PDF uses Letter paper and smaller body text than the site. Images fit the page width and do not split across pages. Each page shows "TREDIS 6 User Manual · Page X of Y" in the footer.
• Done when:
  • Body text in the PDF is smaller than body text on the site.
  • No image is wider than the page or split across two pages.
  • Each page has the footer with its page number.

PRD-0012-US-05: Generate the PDF on each deployment

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As a docs maintainer, I want each deployment to include a current PDF, so that the PDF always matches the site.
• Requirement: The deployment workflow generates the PDF before the Vercel build and checks that the deployment serves it. One command also generates the PDF locally. The command stops every process that it starts, also when it fails. The PDF is not stored in Git.
• Done when:
  • Each preview and production deployment serves /tredis-600/downloads/tredis-6-user-manual.pdf, and the cover shows the deployed commit.
  • The deployment fails when the PDF cannot be generated or is not served.
  • pnpm exec turbo run pdf --filter=@concourse/docs.tredis writes apps/docs.tredis/public/tredis-600/downloads/tredis-6-user-manual.pdf.
  • When Chromium is missing, the command tells the maintainer how to install it.
  • No docs server is still running after the command ends.

Implementation

The /print route in apps/docs.tredis/app/print/ renders every manual page on one HTML page. Search engines do not index it. apps/docs.tredis/lib/print.ts sets the page order, the heading levels, the anchors, and the link rewrites. apps/docs.tredis/scripts/pdf.node.ts builds the app, starts it on a free port, and prints /print with Playwright Chromium. The shared DocsShell in packages/docs shows the "Download PDF" link when the app gives it a pdfUrl.

The TREDIS docs deploy workflow installs Chromium, runs the PDF script before vercel build, and requests the PDF in its route checks. Git ignores the generated file. The README explains how to generate it locally.

Experience and content

• Entry points: the "Download PDF" link in the docs sidebar footer, and the /print page.
• The cover shows "TREDIS 6 User Manual" and "Edition" with the date and commit. A -dirty suffix on the commit shows that the PDF came from uncommitted changes.
• Empty, loading, and error states: Not applicable. The PDF is a static file.
• Access: the PDF and /print are public, like the rest of the manual.
• Accessibility: the PDF is tagged, and its bookmarks follow the heading structure.

Constraints and dependencies

• Playwright and its Chromium browser must be installed where the command runs. The workflow installs them on each run.
• Generating the PDF makes each deployment longer, because the script builds the app before the Vercel build does. The TREDIS docs deploy run shows the time of the PDF step.
• The PDF is a static file, so Vercel Function response limits do not apply to it.
• In local development, the sidebar link returns 404 until a maintainer generates the PDF.
• Chromium cannot put page numbers in the list of contents without a print polyfill.

User documentation

• Audience: docs maintainers.
• Tasks to explain: where the PDF comes from, and how to generate it locally.
• Agreed terms: "PDF of the manual", "Download PDF", "edition".
• Examples or screenshots needed: N/A.
• Published documentation: TREDIS docs README.

Revision history

No revisions.

References

• Original TREDIS help print page
• Playwright page.pdf()