Date: 2026-03-15 Scope: pdfixa-docs (16 doc pages, homepage, examples page, config, sidebar) Perspective: Java backend developer evaluating PDFixa for production use Prior audit: Initial audit conducted same date; this is the post-refactoring reassessment
The drawImage parameter order — page.drawImage(x, y, width, height, imageBytes) — is identical in every file that references it:
content-streams.mdline 45images.mdlines 32, 52api-overview.mdline 67
All three drawTextBox overloads are documented in the API overview and used consistently in guides:
(x, y, w, h, text)— default font(x, y, w, h, text, PdfFont, fontSize)— custom font(x, y, w, h, text, fontSize)— default font, custom size
Both invoice.md and report.md include a dedicated Font setup section that shows how to register fonts via doc.registerFont() before the main code example. report.md also includes a full estimateHeight() implementation with calibration guidance. A developer can copy the guide code and compile it.
The estimateHeight section in report.md now covers:
- How font size, line height, and line count relate (with formula table)
- Two overloads (defaults and full-control)
- Per-font-family character width factors (sans-serif 0.5, serif 0.45, monospace 0.6)
- Tight vs. loose layout examples
- Calibration guidance for when the estimate is off
This is significantly better than the initial single-method stub.
The new error-handling.md covers all four exception scenarios (invalid args, font loading, I/O, null), includes a diagnostic table for font issues, a safe classpath loader, an HTTP disconnect handler, and a complete production try/catch template. This directly addresses production readiness.
colors-and-styling.md explains setColor(r, g, b) for text, lines, fills, and outlines. The color reset pattern and the 8-entry common palette table give developers a ready-to-use starting point.
All 16 doc pages have title, description, and keywords in frontmatter. Titles follow a consistent [Topic] + Java PDF pattern. Keywords target the main search queries: java pdf, pdf generation java, java pdf library, deterministic pdf, plus page-specific terms.
@easyops-cn/docusaurus-search-local is installed with hashed: true. Full-text search across all docs pages from the navbar.
editUrl points to https://github.com/offixa/pdfixa-docs/edit/main/ — every doc page shows a GitHub edit link.
The homepage has four distinct sections:
- Hero with tagline: "Same input. Same bytes. Every time."
- Feature grid (4 columns: deterministic, zero deps, Java 17+, Maven Central)
- Side-by-side code + Maven dependency with
CodeBlockcomponent (syntax highlighted) - Six link cards: Quick Start, Examples, GitHub, Examples repo, Maven Central, API Reference
Sidebar categories:
intro (landing)
Getting Started (expanded) → Installation, Quick Start
Core Concepts (expanded) → Documents, Pages, Content Streams
Features → Fonts, Colors, Images, Metadata, Determinism
Guides → Invoice, Report, Spring Boot
Reference → API Overview, Error Handling
Getting Started and Core Concepts expanded by default — correct for onboarding.
Covers service layer, REST controller, ResponseEntity<byte[]>, streaming with HttpServletResponse, and deterministic caching with ConcurrentHashMap. The cache key now correctly includes a hash of the input data.
Every feature page links to Deterministic Output. Quick Start links to Documents, Pages, and Fonts. Guides link to Core Concepts and Features. The intro landing page has a 4-card grid with directional navigation.
api-overview.md lists all PdfPage methods (drawTextBox, drawLine, drawRect, fillRect, drawImage) but does not include page.setColor(r, g, b). A developer reading the API reference will not find the color method that colors-and-styling.md depends on.
Affected file: reference/api-overview.md
Lines 33, 36, 61, 70, 88 reference boldFont and regularFont without showing how they are created. Unlike the invoice and report guides, this page has no "Font setup" snippet. A developer copying these examples will get a compile error.
Affected file: features/colors-and-styling.md
examples.js lists Getting Started, Core Concepts, Features (4 items), and Guides — but the Features section omits Colors and Styling. The Reference section (API Overview, Error Handling) is entirely missing.
Affected file: src/pages/examples.js
Line 25: doc.writeTo(outputStream); — the variable is not declared in the snippet. Should be FileOutputStream, ByteArrayOutputStream, or at minimum annotated as a placeholder.
Affected file: core-concepts/pages.md
Line 57: cover.fillRect(0, 0, 595, 842); // dark background (requires color support) — now that colors-and-styling.md exists, this comment should link to it.
Affected file: guides/report.md
The footer has 4 columns: Getting Started, Core Concepts, Guides, More. The "More" section only links to API Overview and GitHub — it does not include Colors and Styling or Error Handling.
Affected file: docusaurus.config.js
The `siteConfig.onBrokenMarkdownLinks` config option is deprecated
onBrokenMarkdownLinks: 'warn' should be migrated to markdown.hooks.onBrokenMarkdownLinks per the Docusaurus v4 migration path.
Affected file: docusaurus.config.js
| Topic | Priority | Why |
|---|---|---|
| Testing Guide | High | The determinism page shows a 4-line test. Production teams need a full guide: golden file pattern, hash comparison workflow, CI integration, visual diff tools. |
| FAQ / Troubleshooting | High | "Why is my text at the bottom?", "Why is the PDF empty?", "Why are fonts garbled?". These are the first 3 questions on every PDF library forum. |
| Changelog | Medium | The versioning section in API overview mentions byte-compatibility rules but there is no actual changelog. Developers evaluating for production need release history. |
| Topic | Priority | Why |
|---|---|---|
| Migration from iText / PDFBox | Medium | Competitive positioning — converts evaluators to adopters |
| Performance and memory | Medium | Capacity planning for batch generation |
| Unicode and CJK text | Low | International applications |
| PDF/A compliance | Low | Enterprise archival |
| Javadoc integration | Low | Link from navbar or reference section |
| # | Action | Effort |
|---|---|---|
| 1 | Add page.setColor(r, g, b) to API overview PdfPage section |
1 min |
| 2 | Add a font setup note or snippet to colors-and-styling.md |
2 min |
| 3 | Add Colors and Styling + Error Handling to examples.js |
3 min |
| 4 | Replace outputStream with a concrete variable in pages.md |
1 min |
| 5 | Link "requires color support" comment in report.md to Colors page |
1 min |
| 6 | Add Error Handling to footer links in docusaurus.config.js |
1 min |
| 7 | Migrate onBrokenMarkdownLinks to markdown.hooks format |
1 min |
| # | Action | Effort |
|---|---|---|
| 8 | Write a Testing Guide (golden file, CI, hash comparison) | Medium |
| 9 | Write a FAQ / Troubleshooting page | Medium |
| 10 | Add Changelog page or link to GitHub releases | Low |
| # | Action | Effort |
|---|---|---|
| 11 | Migration Guide from iText / PDFBox | High |
| 12 | Performance and Memory page | Medium |
| 13 | Add Javadoc link in navbar | Low |
| 14 | Add doc versioning | Medium |
| Area | Score | Notes |
|---|---|---|
| API correctness | 9/10 | All method signatures consistent. drawImage order fixed. Three drawTextBox overloads documented. Deduction: setColor missing from API overview. |
| Developer onboarding | 9/10 | Quick Start is copy-paste runnable. Installation covers Maven + Gradle. Guides have font setup. Deduction: colors page has undefined font symbols. |
| Documentation completeness | 8/10 | Fonts, images, metadata, determinism, colors, error handling, pagination, Spring Boot — all covered. Deduction: no testing guide, no FAQ, no changelog. |
| Documentation structure | 9/10 | 5-category sidebar with correct collapse defaults. Homepage has 4 sections. Footer has 4 columns. Deduction: footer and examples page don't include newest pages. |
| Ecosystem integration | 8/10 | GitHub, examples repo, Maven Central all linked from homepage + intro + footer. Edit links enabled. Deduction: no Javadoc link, no changelog link. |
| Documentation UX | 9/10 | Clean code blocks with syntax highlighting. Tables used effectively. Cross-links between pages. Minimal CSS. Deduction: colors page lacks font context. |
| SEO readiness | 9/10 | All 16 pages have title + description + keywords. Titles follow "Java PDF [Topic]" pattern. Deduction: no og:image or social preview card. |
| Discoverability | 9/10 | Local search plugin. Navbar with Home/Docs/Examples/GitHub. Deduction: deprecated config warning (cosmetic). |
Comparison with initial audit: Up from 7/10 to 8.5/10.
| What improved | From → To |
|---|---|
| API consistency | 6 → 9 (drawImage fixed, overloads documented) |
| Guide self-containment | 6 → 9 (font setup, estimateHeight defined) |
| SEO readiness | 4 → 9 (title + description + keywords on all pages) |
| Search | 0 → 9 (local search plugin installed) |
| Coverage | 6 → 8 (colors, error handling, pagination added) |
| Cache bug | fixed (records.hashCode in key) |
To reach 9/10: Fix the 7 Priority-1 items (10 minutes total) and add a Testing Guide. To reach 9.5/10: Add FAQ, Changelog, and Javadoc link.
| Path | Title | description | keywords | Status |
|---|---|---|---|---|
docs/intro.md |
PDFixa Java PDF Library | ✓ | ✓ (5) | OK |
docs/getting-started/installation.md |
PDFixa Installation | ✓ | ✓ (5) | OK |
docs/getting-started/quick-start.md |
Java PDF Quick Start | ✓ | ✓ (5) | OK |
docs/core-concepts/documents.md |
PDF Documents in Java | ✓ | ✓ (5) | OK |
docs/core-concepts/pages.md |
Java PDF Pages and Coordinates | ✓ | ✓ (5) | outputStream undefined |
docs/core-concepts/content-streams.md |
Java PDF Content Streams | ✓ | ✓ (5) | OK |
docs/features/fonts.md |
Java PDF Fonts | ✓ | ✓ (5) | OK |
docs/features/colors-and-styling.md |
Java PDF Colors and Styling | ✓ | ✓ (5) | boldFont/regularFont undefined |
docs/features/images.md |
Java PDF Images | ✓ | ✓ (5) | OK |
docs/features/metadata.md |
Java PDF Metadata | ✓ | ✓ (5) | OK |
docs/features/deterministic-output.md |
Deterministic PDF in Java | ✓ | ✓ (5) | OK |
docs/guides/invoice.md |
Java Invoice PDF Guide | ✓ | ✓ (5) | OK |
docs/guides/report.md |
Java PDF Report Guide | ✓ | ✓ (5) | color comment needs link |
docs/guides/spring-boot.md |
Spring Boot PDF Generation | ✓ | ✓ (5) | OK |
docs/reference/api-overview.md |
PDFixa API Overview | ✓ | ✓ (5) | setColor missing |
docs/reference/error-handling.md |
PDFixa Error Handling | ✓ | ✓ (5) | OK |