From d15fc5c6beeaea2a02ade9399cc0f6ff2421d6b3 Mon Sep 17 00:00:00 2001 From: yiling Date: Sun, 9 Aug 2026 14:49:07 +0800 Subject: [PATCH] update doc --- docs/docs.json | 4 ++-- docs/using-shumai/gotenberg.mdx | 23 +---------------------- 2 files changed, 3 insertions(+), 24 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 6af931a1..fffcd3f5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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" ] }, { diff --git a/docs/using-shumai/gotenberg.mdx b/docs/using-shumai/gotenberg.mdx index 38a588d0..f898d1f7 100644 --- a/docs/using-shumai/gotenberg.mdx +++ b/docs/using-shumai/gotenberg.mdx @@ -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.