update doc

This commit is contained in:
yiling
2026-08-09 14:49:07 +08:00
parent aa6d5ed626
commit d15fc5c6be
2 changed files with 3 additions and 24 deletions
+2 -2
View File
@@ -26,7 +26,6 @@
"group": "Using Shumai",
"pages": [
"using-shumai/asset-management",
"using-shumai/gotenberg",
"using-shumai/comments",
"using-shumai/version-stack",
"using-shumai/sort-and-search",
@@ -35,7 +34,8 @@
"using-shumai/notifications",
"using-shumai/metadata",
"using-shumai/collections",
"using-shumai/share-links"
"using-shumai/share-links",
"using-shumai/gotenberg"
]
},
{
+1 -22
View File
@@ -3,7 +3,7 @@ title: Document PDF Conversion with Gotenberg
description: Convert Office documents, HTML, Markdown, CSV, and TXT files into high-fidelity PDF proxies for in-browser previewing.
---
Office documents, HTML pages, Markdown files, spreadsheets, and plain-text files cannot be rendered natively in web browsers. Shumai uses [Gotenberg](https://gotenberg.dev) — an open-source, Docker-powered conversion API — to turn these files into PDF proxy assets for seamless in-browser previewing.
Office documents, HTML pages, Markdown files, spreadsheets, and plain-text files cannot be rendered natively in web browsers. Shumai uses [Gotenberg](https://gotenberg.dev), an open-source, Docker powered conversion API — to turn these files into PDF proxy assets for seamless in-browser previewing.
Gotenberg performs the conversion using:
@@ -28,17 +28,6 @@ When Gotenberg is configured, Shumai automatically generates a PDF proxy for the
| Spreadsheets / CSV | `.csv` | LibreOffice |
| Plain text | `.txt` | LibreOffice |
### How It Works
1. The file is uploaded and stored in its original form.
2. Shumai submits a background `transcode_pdf` task to the workflow engine.
3. Gotenberg converts the file into a `proxy.pdf` asset.
4. The PDF proxy is further processed into a **poster** WebP image and a **sprite** WebP image, enabling fast, high-fidelity previews in the asset list and viewer.
**Automatic landscape optimization**: Spreadsheets and CSV files with more than 5 columns are automatically converted in landscape layout so wide tables remain readable.
**Markdown rendering**: Markdown content is rendered by Chromium through an `index.html` wrapper template (`{{ toHTML "file.md" }}`), producing clean, styled PDF output.
---
## Configuration
@@ -91,13 +80,3 @@ If Gotenberg is not configured or unreachable, Shumai degrades gracefully:
- **Office documents and HTML**: the upload completes as `processed` without a PDF proxy.
- **CSV, Markdown, and TXT**: a lightweight built-in PDF generator produces the proxy instead, with reduced fidelity.
---
## Security Considerations
Gotenberg renders user-uploaded HTML and Markdown in a headless Chromium instance, which may fetch referenced remote resources (images, stylesheets, links). If your deployment exposes Gotenberg to untrusted content, we recommend:
- Running Gotenberg in an isolated network segment with restricted egress.
- Configuring Gotenberg's Chromium allow-list (`--chromium-allow-list`) to constrain which URLs Chromium may access.
- Applying resource limits (CPU/memory) to the Gotenberg container.