Document Gotenberg-powered file conversion for non-core formats

[JSv4]

Summary

• Adds a "Convertible Formats (via Gotenberg)" section to docs/upload_methods/supported_formats.md, explaining the ~126 LibreOffice-backed extensions (legacy Office, OpenDocument, iWork, WordPerfect, images, HTML, ...) the optional pre-parse file converter can turn into PDF, how conversion fits into the ingest pipeline, and where the live/authoritative extension list lives.
• Adds a screenshotted "File Converters (Gotenberg)" walkthrough to docs/pipelines/pipeline_configuration.md with step-by-step instructions for enabling/disabling conversion via the Admin UI (with new screenshots) or the DEFAULT_FILE_CONVERTER env var, plus a note that the gotenberg compose service already ships in local.yml/production.yml and needs no compose-file changes to use.
• Adds an "Optional Services" section to docs/configuration/choose-and-configure-docker-stack.md documenting gotenberg (and pointers to warp-ingest/privacy_filter).
• Documents GOTENBERG_SERVICE_URL, GOTENBERG_CONVERTER_TIMEOUT, and DEFAULT_FILE_CONVERTER in the sample .django env files.
• Updates README.md's "Supported Formats" section and documentation table to mention the conversion capability.
• Minor cross-link updates in docs/upload_methods/index.md and single_upload.md to mention the pre-parse conversion step.

Screenshots

New data-testid="file-converter-row" on the File Converter row in FiletypeDefaults.tsx, and three new docScreenshot captures in the existing "file converter on/off" Playwright component test suite (frontend/tests/system-settings-flows.ct.tsx) back the walkthrough:

• admin--pipeline-settings--file-converter-disabled.png
• admin--pipeline-settings--file-converter-picker.png
• admin--pipeline-settings--file-converter-enabled.png

These were generated locally by running the actual component tests (not hand-crafted), so they reflect the real UI.

Test plan

• yarn tsc --noEmit passes
• yarn test:ct --reporter=list -g "file converter on/off" — both tests pass, screenshots generated
• pre-commit (configured hooks) pass on all changed files
• python scripts/collate_changelog.py --check passes
• Manually reviewed all internal doc links/anchors for correctness

🤖 Generated with Claude Code

---

Generated by Claude Code

[claude]

Review

Docs-focused PR (README, docs/upload_methods/, docs/pipelines/pipeline_configuration.md, docs/configuration/choose-and-configure-docker-stack.md, sample env files) plus one small frontend change (a data-testid addition and three new docScreenshot calls in an existing Playwright suite). No backend/business-logic changes.

Verification performed

I cross-checked the technical claims in the docs against the current code rather than taking them at face value:

• "126 file extensions" (docs/upload_methods/supported_formats.md) — counted GOTENBERG_SUPPORTED_EXTENSIONS in opencontractserver/pipeline/file_converters/gotenberg_converter.py: exactly 126 entries. ✅
• convertibleExtensions GraphQL query — confirmed it exists (config/graphql/pipeline_queries.py:315, exposed in schema.graphql:7879) and is consumed by UploadModal.tsx / FileDropZone.tsx exactly as described (unioned with core formats, "+N convertible formats" label). ✅
• migrate_pipeline_settings --sync-preferences flag — exists and matches the documented behavior (opencontractserver/documents/management/commands/migrate_pipeline_settings.py). ✅
• gotenberg compose service — required: false dependency and no published host port confirmed in local.yml/production.yml; matches the "sits idle until configured" and "stack still starts if removed" claims. ✅
• docScreenshot(..., { element }) usage in the test file matches the utility's actual signature (frontend/tests/utils/docScreenshot.ts). ✅

I did not find any factual inaccuracies in the documentation — this is a well-verified PR, consistent with the stated test plan (tsc, targeted Playwright run, changelog check, manual link review).

Minor observations (non-blocking)

1. FiletypeDefaults.tsx diff is purely a test hook. Adding data-testid="file-converter-row" to FiletypeRow is a reasonable, low-risk way to scope the new screenshots to just that row rather than the whole panel — no concerns there.

2. Extension table in supported_formats.md is explicitly marked "illustrative, not exhaustive" and points to the live source (GOTENBERG_SUPPORTED_EXTENSIONS) and the GraphQL query as the source of truth. Good call — this avoids the table silently drifting out of sync the next time the extension list changes, which is exactly the kind of doc rot CLAUDE.md warns about.

3. Slight redundancy across three docs (README.md, supported_formats.md, pipeline_configuration.md, choose-and-configure-docker-stack.md) explaining "the gotenberg service already runs, no compose changes needed." This is intentional cross-linking for readers who land on any one page, and each instance is short with a pointer to the canonical explanation, so it reads as acceptable duplication rather than copy-paste drift.

4. docs/upload_methods/single_upload.md now says a convertible-format upload "is stored as inert application/octet-stream until conversion succeeds" — worth a quick double-check that this matches current ingest code behavior (I didn't trace the full ingest task in this review), since it's a fairly specific implementation detail to assert in user-facing docs. If it's already covered by pipeline_overview.md#file-converters (referenced elsewhere in this PR), it's likely fine.

5. Changelog fragment (changelog.d/gotenberg-docs-overhaul.changed.md) follows the required per-PR fragment convention correctly.

Test coverage

The three new docScreenshot calls are additive to an existing, already-passing test suite (system-settings-flows.ct.tsx) and don't change assertions — low risk. The expanded supportedExtensions mock array (4 → 10 entries) is cosmetic (just makes the screenshot more representative) and doesn't affect test logic.

Security

No security-relevant code changes. The docs appropriately point readers to the pipeline architecture doc for the "SSRF/stored-content security posture" discussion rather than re-explaining it here, avoiding duplicated (and potentially drifting) security guidance.

Overall: Solid, accurate, well-scoped documentation PR. No blocking issues found.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!