Files
shumai/docs/using-shumai/gotenberg.mdx
T
2026-08-09 14:49:07 +08:00

83 lines
3.1 KiB
Plaintext

---
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.
Gotenberg performs the conversion using:
- **LibreOffice** for Office documents, spreadsheets, and plain text.
- **Headless Chromium** for HTML and Markdown files.
---
## Supported File Types
When Gotenberg is configured, Shumai automatically generates a PDF proxy for the following uploads:
| Category | Extensions | Converter |
| ------------------ | ---------------------- | ----------- |
| Word | `.doc`, `.docx` | LibreOffice |
| Excel | `.xls`, `.xlsx` | LibreOffice |
| PowerPoint | `.ppt`, `.pptx` | LibreOffice |
| OpenDocument | `.odt`, `.ods`, `.odp` | LibreOffice |
| Rich Text | `.rtf` | LibreOffice |
| HTML | `.html`, `.htm` | Chromium |
| Markdown | `.md`, `.markdown` | Chromium |
| Spreadsheets / CSV | `.csv` | LibreOffice |
| Plain text | `.txt` | LibreOffice |
---
## Configuration
Gotenberg support is opt-in and controlled by the following environment variables on the machine running the transcode workers:
| Variable | Required | Description |
| ------------------------------- | --------------- | ---------------------------------------------------------------- |
| `GOTENBERG_URL` | Yes (to enable) | Base URL of the Gotenberg service, e.g. `http://gotenberg:3000`. |
| `GOTENBERG_BASIC_AUTH_USERNAME` | No | Username when Basic Authentication is enabled on Gotenberg. |
| `GOTENBERG_BASIC_AUTH_PASSWORD` | No | Password when Basic Authentication is enabled on Gotenberg. |
### Docker Quickstart
You can start a Gotenberg container with a single command:
```bash
docker run -d --name gotenberg -p 3000:3000 gotenberg/gotenberg:8
```
If you wish to enable Basic Authentication:
```bash
docker run -d --name gotenberg -p 3000:3000 gotenberg/gotenberg:8 gotenberg --gotenberg-basic-auth-username=admin --gotenberg-basic-auth-password=secret
```
### Docker Compose Setup
Add a Gotenberg service to your `docker-compose.yaml`:
```yaml
gotenberg:
image: gotenberg/gotenberg:8
restart: unless-stopped
ports:
- '3000:3000'
```
Then point Shumai at it:
```bash
GOTENBERG_URL=http://localhost:3000
```
---
## Behavior Without Gotenberg
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.