diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index d7588f32..00000000 --- a/AGENTS.md +++ /dev/null @@ -1,340 +0,0 @@ -# Operational Guidelines for Gotenberg Documentation - -You are working on **gotenberg.dev**, the official documentation website for [Gotenberg](https://github.com/gotenberg/gotenberg), a Docker-based API for converting documents to PDF. This is a Docusaurus 3.x site serving the public-facing docs at https://gotenberg.dev. Accuracy and clarity are paramount: users rely on this documentation to integrate Gotenberg into production systems. - -## Mandatory Workflow - -Every task follows these five steps **in order**. Do not skip or reorder them. - -### Step 1: Plan - -Before writing any code or content: - -1. State the problem or request. -2. Propose a solution. -3. List alternatives when pertinent. -4. Define scope: which files will be created, modified, or deleted. -5. Describe the verification strategy. - -**Wait for user approval before proceeding.** - -### Step 2: Implement - -Execute the approved plan. After implementation, verify the site builds cleanly: - -```bash -npm run build -``` - -### Step 3: Test - -Verify the changes: - -- All links and imports resolve correctly. -- cURL examples are valid and copy-pasteable. -- Form field names, types, and defaults match the actual Gotenberg API. -- Components render correctly at desktop (1440px), laptop (1024px), and tablet (768px) widths. -- No console errors or React warnings in the browser. - -### Step 4: Review - -Self-review against this checklist, then present findings to the user: - -- [ ] **Accuracy.** Every endpoint path, form field name, code sample, and configuration flag matches the actual Gotenberg API. -- [ ] **Backward compatibility.** No broken links, no removed content without replacement, no changed URLs. -- [ ] **Consistency.** Follows established page structure, component usage, and terminology. -- [ ] **Code quality.** Formatted with Prettier (`npm run format`), no linting errors, no unused imports. -- [ ] **Documentation.** Shared partials used where appropriate. No duplicated content across pages. -- [ ] **Build.** `npm run build` passes without errors or warnings. - -### Step 5: Commit - -**Only after explicit user approval.** - -- Use [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `docs:`, `feat:`, `fix:`, `style:`). -- Stage specific files only. Never `git add -A` or `git add .`. -- Write a concise commit message that explains _why_, not just _what_. - ---- - -## Core Principles - -- **Accuracy is law.** Every code sample, form field name, endpoint path, and configuration flag must match the actual Gotenberg API. When in doubt, cross-reference with the [Gotenberg source](https://github.com/gotenberg/gotenberg). -- **Direct, confident tone.** Short declarative sentences. No filler words, no hedging ("you might want to", "please feel free to"). Say what something does, not what it is. Lead with the action or outcome. -- **No robotic patterns.** Never start with "This endpoint...", "This route...", or "Use the X form field to...". Describe what it does for the user, not what the object is. -- **Inline over admonitions.** Integrate warnings and notes into prose. Reserve `:::info`, `:::warning`, `:::danger` for genuinely critical information that must stand out. Most pages should have zero or one admonition. -- **No "we" hedging.** Avoid "We do not recommend...", "We offer...", "We have...". Speak directly: "Don't expose...", "There's a dedicated image...". -- **One sentence, not two.** If the second sentence restates the first with more words, delete it. -- **No em dashes.** Never use `—` in any markdown file. Use a period, colon, or comma instead. -- **Consistency.** Follow established patterns for page structure, component usage, and terminology. Every API doc page uses the same layout and components. -- **No broken builds.** The site must build cleanly (`npm run build`) before any change is considered complete. - -## Quick Reference - -- Dev server: `npm start` -- Production build: `npm run build` -- Format: `npm run format` (Prettier) -- Serve built site: `npm run serve` -- Clear cache: `npm run clear` - -## Key Components and Patterns - -### ApiEndpoint Component - -All API endpoint documentation uses the `` React component (`src/components/documentation/ApiEndpoint.js`). It accepts: - -- `method`: HTTP method (GET, POST, HEAD) -- `path`: Endpoint path (e.g., `/forms/chromium/convert/html`) -- `headers`: Array of `{ name, type, required, description }` objects -- `formFields`: Array of `{ name, type, required, description, defaultValue }` objects -- `formFiles`: Array of `{ name, type, required, description }` objects -- `curl`: Example cURL command string -- `responses`: Array of `{ status, description, body }` objects - -### Shared MDX Partials - -Common features (encryption, PDF/A, metadata, etc.) are documented as reusable `_shared/` partials imported into multiple pages. When modifying a shared feature, check all pages that import it. - -### Sidebar Configuration - -`sidebars.js` defines the navigation. API endpoints use `className: "sidebar-method-post"` (or `-get`, `-head`) to display HTTP method badges. - -### Styling - -- Primary color: `#008ae6` (blue) -- Font: Inter (body), JetBrains Mono (code) -- Light mode only (dark mode disabled) -- Admonitions: `:::info`, `:::warning`, `:::danger`, `:::tip` with custom hover effects - -## Codebase Navigation - -- Documentation content (MDX files) lives in `docs/`, React components and styles in `src/`, and site configuration in root files (`sidebars.js`, `docusaurus.config.js`). -- Start with `sidebars.js` to understand the documentation structure. -- API doc pages follow a consistent pattern: intro paragraph, ``, basics section with ``, then imported shared partials for additional features. -- Shared partials in `docs/convert-with-chromium/_shared/` cover Chromium-specific features (headers/footers, rendering behavior, HTTP networking, console output, assets). -- Shared partials in `docs/_shared/` cover PDF engine features (encryption, flatten, metadata, PDF/A, attachments). -- The homepage (`src/components/Homepage.js`) is a custom React component, not an MDX page. - ---- - -## Writer Reference - -Content for writing or editing documentation pages (new pages, fixing docs, rewording, editing `.mdx` files). - -### Page Structure Convention - -Every API endpoint documentation page follows this structure: - -1. **Frontmatter:** `id` and `title` fields -2. **Imports:** Shared MDX partials and React components -3. **Intro line:** One direct sentence saying what the endpoint does -4. **Configuration link:** Links to the configuration page for related flags (Chromium/LibreOffice pages) -5. **`## Basics`:** The `` component with method, path, headers, form fields/files, cURL example, and responses. Only used on pages with multiple sections; single-section pages skip this heading. -6. **Feature sections:** Each sub-section owns its form fields directly (no summary-then-detail duplication). Shared partials with `showFormFields={true}` render their own field definitions. -7. **``:** Sponsor component at the bottom - -New pages must follow existing pages as templates. - -### Writing Style - -- **Short, declarative sentences.** Say what it does, then stop. No filler, no hedging. -- **Lead with the action.** "Merges multiple PDF files" not "This endpoint allows you to merge multiple PDF files". -- **Use second person sparingly.** "your files", "your HTML", but don't overuse "you can". -- **Prefer active voice.** "Gotenberg converts the file" not "The file is converted by Gotenberg". -- **Inline over admonitions.** Integrate caveats into prose. Only use `:::info`, `:::warning`, `:::danger` for genuinely critical information. -- **No "Use the X form field to..." pattern.** Describe the outcome directly: "Inject XMP metadata into the PDF" not "Use the `metadata` form field to inject XMP metadata". -- **Use inline code** for all technical terms: form field names (`url`), header names (`Gotenberg-Trace`), endpoint paths (`/forms/chromium/convert/url`), file names (`index.html`), CLI flags (`--api-port`), and environment variables. - -### ApiEndpoint Component Usage - -When documenting an API endpoint, use the `` component. All parameters must be accurate. - -```jsx - -``` - -Key rules: - -- The `curl` example must be a valid, copy-pasteable command. -- Response descriptions must match Gotenberg's actual behavior. -- Use `defaultValue` in form fields when a default exists. -- Mark fields as `required: true` only when they are genuinely required. - -### Shared Partials - -Reusable documentation blocks live in `_shared/` directories: - -- `docs/convert-with-chromium/_shared/`: Chromium features (assets, console, encryption, header/footer, HTTP networking, rendering behavior, structure metadata, PDF/A, split/page ranges) -- `docs/_shared/`: PDF engine features (attachments, encryption, flatten, metadata, PDF/A-UA, syntax validation) - -When a feature applies to multiple endpoints, it MUST be a shared partial. Never duplicate content across pages. Import the partial instead. - -### Admonitions - -Use Docusaurus admonitions for callouts: - -```mdx -:::info -Informational note about behavior or context. -::: - -:::warning -Important caveat or potential pitfall. -::: - -:::danger -Breaking behavior, data loss risk, or critical limitation. -::: - -:::tip -Helpful suggestion or best practice. -::: -``` - -Reserve `:::danger` for genuinely dangerous situations. Use `:::info` for most callouts. - -### Sidebar Updates - -When adding a new page, update `sidebars.js`: - -- API endpoints must include `className: "sidebar-method-post"` (or `-get`, `-head`) for the HTTP method badge. -- Place the page in the correct category following the existing order. -- Use `type: "doc"` with the document `id` matching the frontmatter. - -### Versioning - -The site supports versioned documentation (`versioned_docs/`, `versions.json`). Current docs live in `docs/`. Do not modify versioned docs unless explicitly asked. Changes to `docs/` apply to the current (next) version only. - ---- - -## Designer Reference - -Content for modifying site design, React components, styles, or layout (CSS, theme, homepage, `.js`/`.css` files). - -### Technology Stack - -- **Framework:** Docusaurus 3.8.1 (React 18) -- **Styling:** CSS Modules (`.module.css`) for components, global CSS (`src/css/custom.css`) for theme overrides -- **Fonts:** Inter (body, headings), JetBrains Mono (code), loaded via Google Fonts -- **Icons:** Inline SVGs in React components (no icon library) -- **Images:** `@docusaurus/plugin-ideal-image` for optimized images - -### Design System - -#### Colors - -| Token | Value | Usage | -| ------------------------------- | --------- | ----------------------------- | -| `--ifm-color-primary` | `#008ae6` | Links, accents, primary CTA | -| `--ifm-heading-color` | `#0f172a` | H1 headings | -| `--ifm-color-content` | `#334155` | Body text | -| `--ifm-color-content-secondary` | `#64748b` | Secondary text, sidebar links | -| `--ifm-border-color` | `#e2e8f0` | Borders, dividers | - -HTTP method badge colors: - -- POST: `#49cc90` (green) -- GET: `#61affe` (blue) -- PUT: `#fca130` (orange) -- DELETE: `#f93e3e` (red) -- HEAD: `#9061f9` (purple) - -#### Typography - -- H1: 3rem, weight 900, letter-spacing -0.03em, blue bottom border -- H2: 1.8rem, weight 800, letter-spacing -0.02em, gray bottom border -- H3: 1.4rem, weight 700, blue left border with padding -- Body: 1.05rem, line-height 1.75 -- Code: 0.85em, weight 500, subtle gray background - -#### Spacing and Layout - -- Max content width: 840px (`.theme-doc-markdown`) -- Container width: 1366px -- Navbar height: 4rem -- Light mode only (dark mode switch is disabled) - -### Component Architecture - -#### Homepage (`src/components/Homepage.js`) - -A standalone React component with CSS Modules (`Homepage.module.css`). Contains: - -- Hero section with logo, tagline, and CTA buttons -- Community stats strip (Docker pulls, GitHub stars, license) -- Feature blocks with `SimpleTerminal` code previews -- Final CTA section - -The `SimpleTerminal` component renders syntax-highlighted bash commands with a macOS-style window chrome (red/yellow/green dots). - -#### ApiEndpoint (`src/components/documentation/ApiEndpoint.js`) - -The core documentation component. Renders API endpoint information with: - -- Method badge + path header -- Collapsible parameter lists (headers, form fields, form files) -- cURL example via Docusaurus `` -- Tabbed response display via Docusaurus `` - -This component has its own CSS Module (`ApiEndpoint.module.css`). - -#### Sponsors (`src/components/documentation/Sponsors.js`) - -Renders sponsor logos at the bottom of documentation pages. - -### Theme Overrides - -- `src/theme/DocSidebar/index.js`: Custom sidebar with HTTP method badges via CSS pseudo-elements -- Sidebar badges are implemented purely in CSS using `::before` pseudo-elements on `.sidebar-method-*` classes - -### CSS Conventions - -- Use CSS custom properties (`--ifm-*`) for Docusaurus theme values -- Use CSS Modules for component-scoped styles -- Use `src/css/custom.css` only for global overrides (admonitions, sidebar, footer, typography) -- Transitions: `0.2s ease` for interactive elements, `0.3s cubic-bezier(0.4, 0, 0.2, 1)` for larger animations -- Hover effects: subtle `translateY(-1px)` lift with colored box-shadow -- Use `clsx` for conditional class composition in React components - -### Docusaurus Integration - -- Respect Docusaurus's Infima CSS framework. Override with specificity, not `!important` (except documented exceptions). -- Use `@docusaurus/Link` for internal navigation, not `` tags -- Use `useBaseUrl` for static asset paths -- Swizzled components live in `src/theme/`. Be cautious when upgrading Docusaurus. - -### Responsive Design - -- Tables switch to horizontal scroll below 1280px -- Content padding adjusts at 996px and 1400px breakpoints -- Homepage uses Docusaurus grid system (`col col--6`, `row`, `container`) diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 00000000..eada936c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CONTRIBUTING.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 7f277f8c..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,3 +0,0 @@ -# Claude Code — Gotenberg Documentation - -Read [AGENTS.md](AGENTS.md) first. It is the root context: mandatory workflow, core principles, project layout, quick reference, and all reference material (writer and designer). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000..eada936c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +CONTRIBUTING.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 493b1f1a..ca513643 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,6 @@ -# Contributing to Gotenberg Documentation +# Contributing to gotenberg.dev -Thank you for your interest in contributing to the Gotenberg documentation! This guide will help you get started. - -## Before You Start - -Please read the [AGENTS.md](AGENTS.md) file — it describes the core principles, project layout, and documentation standards that all contributions must follow. Even though it is written for AI agents, the same rules apply to human contributors. It also contains the Writer and Designer reference sections with page structure conventions, writing style, design system, and component usage. +This is the official documentation website for [Gotenberg](https://github.com/gotenberg/gotenberg), a Docker-based API for converting documents to PDF. Built with Docusaurus 3.x, served at https://gotenberg.dev. Accuracy and clarity are paramount: users rely on this documentation to integrate Gotenberg into production systems. ## Getting Started @@ -13,17 +9,16 @@ Please read the [AGENTS.md](AGENTS.md) file — it describes the core principles - Node.js (LTS recommended) - npm -### Install and Run +### Build and Run ```bash -npm install # Install dependencies -npm start # Start the dev server (http://localhost:3000) +npm install +npm start # Dev server at http://localhost:3000 ``` ### Development Loop ```bash -# Write your content or code, then: npm run format # Format all files with Prettier npm run build # Verify the site builds without errors npm run serve # Preview the production build locally @@ -31,18 +26,95 @@ npm run serve # Preview the production build locally ## Submitting a Pull Request +For non-trivial changes, outline your approach in the PR description: what you're changing, why, and which files are affected. This helps reviewers and prevents wasted effort. + Before opening a PR, verify: -1. Site builds without errors: `npm run build` -2. Files are formatted: `npm run format` -3. All links and imports resolve correctly -4. cURL examples are valid and copy-pasteable -5. Form field names, types, and defaults match the actual Gotenberg API +- [ ] Site builds without errors: `npm run build` +- [ ] Files are formatted: `npm run format` +- [ ] All links and imports resolve correctly +- [ ] cURL examples are valid and copy-pasteable +- [ ] Form field names, types, and defaults match the actual Gotenberg API +- [ ] Components render correctly at desktop (1440px), laptop (1024px), and tablet (768px) widths +- [ ] No console errors or React warnings in the browser ### Guidelines - **Accuracy first.** Every endpoint path, form field name, and code sample must match the actual Gotenberg API. When in doubt, cross-reference with the [Gotenberg source](https://github.com/gotenberg/gotenberg). - **One thing per PR.** Keep content changes, component changes, and style changes in separate PRs when possible. - **Follow established patterns.** New API doc pages must use the `` component and follow the same structure as existing pages. -- **Use shared partials.** If a feature applies to multiple endpoints, document it as a reusable `_shared/` partial — never duplicate content across pages. -- **Don't break versioned docs.** Changes to `docs/` apply to the current version only. Do not modify `versioned_docs/` unless explicitly needed. +- **Use shared partials.** If a feature applies to multiple endpoints, document it as a reusable `_shared/` partial. Never duplicate content across pages. +- **Don't break versioned docs.** Changes to `docs/` apply to the current version only. Don't modify `versioned_docs/` unless explicitly needed. + +### Commit Conventions + +If committing, follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `docs:`, `feat:`, `fix:`, `style:`). Stage specific files only. Never `git add -A` or `git add .`. Write a concise commit message that explains _why_, not just _what_. + +## Core Principles + +- **Accuracy is law.** Every code sample, form field name, endpoint path, and configuration flag must match the actual Gotenberg API. When in doubt, cross-reference with the [Gotenberg source](https://github.com/gotenberg/gotenberg). +- **Direct, confident tone.** Short declarative sentences. No filler words, no hedging ("you might want to", "please feel free to"). Say what something does, not what it is. Lead with the action or outcome. +- **No robotic patterns.** Never start with "This endpoint...", "This route...", or "Use the X form field to...". Describe what it does for the user, not what the object is. +- **Inline over admonitions.** Integrate warnings and notes into prose. Reserve `:::info`, `:::warning`, `:::danger` for genuinely critical information that must stand out. Most pages should have zero or one admonition. +- **No "we" hedging.** Avoid "We do not recommend...", "We offer...", "We have...". Speak directly: "Don't expose...", "There's a dedicated image...". +- **One sentence, not two.** If the second sentence restates the first with more words, delete it. +- **No em dashes.** Never use `—` in any markdown file. Use a period, colon, or comma instead. +- **Consistency.** Follow established patterns for page structure, component usage, and terminology. Every API doc page uses the same layout and components. +- **No broken builds.** The site must build cleanly (`npm run build`) before any change is considered complete. + +## Project Layout + +``` +docs/ MDX documentation content + _shared/ Shared partials for PDF engine features + convert-with-chromium/ Chromium endpoint docs + _shared/ partials + convert-with-libreoffice/ LibreOffice endpoint docs + getting-started/ Introduction, installation, clients + manipulate-pdfs/ PDF manipulation endpoint docs + system/ Health, version, debug, metrics endpoint docs + configuration.mdx Module configuration reference + troubleshooting.mdx Common issues and solutions + webhook-download.mdx Webhook and download-from docs + telemetry.mdx Telemetry docs +src/ + components/ React components (Homepage, ApiEndpoint, Sponsors) + css/ Global CSS (custom.css) + pages/ Custom pages (index.js) + theme/ Docusaurus theme overrides (DocSidebar) +sidebars.js Navigation structure +docusaurus.config.js Site configuration +``` + +## Codebase Navigation + +- Start with `sidebars.js` to understand the documentation structure. +- API doc pages follow a consistent pattern: intro paragraph, ``, basics section with ``, then imported shared partials for additional features. +- Shared partials in `docs/convert-with-chromium/_shared/` cover Chromium-specific features (headers/footers, rendering behavior, HTTP networking, console output, assets). +- Shared partials in `docs/_shared/` cover PDF engine features (encryption, flatten, metadata, PDF/A, attachments). +- The homepage (`src/components/Homepage.js`) is a custom React component, not an MDX page. + +## npm: the Only Build Interface + +| Command | Purpose | +| :--------------- | :--------------------------------- | +| `npm start` | Start the dev server | +| `npm run build` | Production build | +| `npm run format` | Format all files with Prettier | +| `npm run serve` | Serve the production build locally | +| `npm run clear` | Clear the Docusaurus cache | + +## Review Checklist + +- [ ] **Accuracy.** Every endpoint path, form field name, code sample, and configuration flag matches the actual Gotenberg API. +- [ ] **Backward compatibility.** No broken links, no removed content without replacement, no changed URLs. +- [ ] **Consistency.** Follows established page structure, component usage, and terminology. +- [ ] **Code quality.** Formatted with Prettier (`npm run format`), no linting errors, no unused imports. +- [ ] **Documentation.** Shared partials used where appropriate. No duplicated content across pages. +- [ ] **Build.** `npm run build` passes without errors or warnings. + +## Scoped Guidelines + +Domain-specific reference material lives in subdirectory READMEs: + +- [Documentation content](docs/README.md): writing style, page structure, ApiEndpoint component, shared partials, admonitions, sidebar, versioning +- [Site design and components](src/README.md): technology stack, design system, component architecture, CSS conventions, responsive design diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 52fe0581..00000000 --- a/GEMINI.md +++ /dev/null @@ -1,3 +0,0 @@ -# Gemini — Gotenberg Documentation - -Read [AGENTS.md](AGENTS.md) first. It is the root context: mandatory workflow, core principles, project layout, quick reference, and all reference material (writer and designer). diff --git a/GEMINI.md b/GEMINI.md new file mode 120000 index 00000000..eada936c --- /dev/null +++ b/GEMINI.md @@ -0,0 +1 @@ +CONTRIBUTING.md \ No newline at end of file diff --git a/README.md b/README.md index 14892e0e..040d7ddf 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,14 @@ # gotenberg.dev -This is the source of the official [Gotenberg website](https://gotenberg.dev). +The official documentation website for [Gotenberg](https://github.com/gotenberg/gotenberg), served at https://gotenberg.dev. -## Installation +Built with [Docusaurus 3.x](https://docusaurus.io/). -```bash -npm install -``` - -## Local Development +## Quick Start ```bash +npm install npm start ``` -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. - -## Prettier - -```bash -npm run format -``` - -This command formats the source code. +See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines, project layout, and how to submit changes. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..8925d74b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,127 @@ +# Documentation Content + +Guidelines for writing or editing documentation pages: new pages, fixing docs, rewording, editing `.mdx` files. + +## Page Structure Convention + +Every API endpoint documentation page follows this structure: + +1. **Frontmatter:** `id` and `title` fields +2. **Imports:** Shared MDX partials and React components +3. **Intro line:** One direct sentence saying what the endpoint does +4. **Configuration link:** Links to the configuration page for related flags (Chromium/LibreOffice pages) +5. **`## Basics`:** The `` component with method, path, headers, form fields/files, cURL example, and responses. Only used on pages with multiple sections; single-section pages skip this heading. +6. **Feature sections:** Each sub-section owns its form fields directly (no summary-then-detail duplication). Shared partials with `showFormFields={true}` render their own field definitions. +7. **``:** Sponsor component at the bottom + +New pages must follow existing pages as templates. + +## Writing Style + +- **Short, declarative sentences.** Say what it does, then stop. No filler, no hedging. +- **Lead with the action.** "Merges multiple PDF files" not "This endpoint allows you to merge multiple PDF files". +- **Use second person sparingly.** "your files", "your HTML", but don't overuse "you can". +- **Prefer active voice.** "Gotenberg converts the file" not "The file is converted by Gotenberg". +- **Inline over admonitions.** Integrate caveats into prose. Only use `:::info`, `:::warning`, `:::danger` for genuinely critical information. +- **No "Use the X form field to..." pattern.** Describe the outcome directly: "Inject XMP metadata into the PDF" not "Use the `metadata` form field to inject XMP metadata". +- **Use inline code** for all technical terms: form field names (`url`), header names (`Gotenberg-Trace`), endpoint paths (`/forms/chromium/convert/url`), file names (`index.html`), CLI flags (`--api-port`), and environment variables. + +## ApiEndpoint Component + +All API endpoint documentation uses the `` React component (`src/components/documentation/ApiEndpoint.js`). It accepts: + +- `method`: HTTP method (GET, POST, HEAD) +- `path`: Endpoint path (e.g., `/forms/chromium/convert/html`) +- `headers`: Array of `{ name, type, required, description }` objects +- `formFields`: Array of `{ name, type, required, description, defaultValue }` objects +- `formFiles`: Array of `{ name, type, required, description }` objects +- `curl`: Example cURL command string +- `responses`: Array of `{ status, description, body }` objects + +Example: + +```jsx + +``` + +Key rules: + +- The `curl` example must be a valid, copy-pasteable command. +- Response descriptions must match Gotenberg's actual behavior. +- Use `defaultValue` in form fields when a default exists. +- Mark fields as `required: true` only when they are genuinely required. + +## Shared Partials + +Reusable documentation blocks live in `_shared/` directories: + +- `docs/convert-with-chromium/_shared/`: Chromium features (assets, console, encryption, header/footer, HTTP networking, rendering behavior, structure metadata, PDF/A, split/page ranges) +- `docs/_shared/`: PDF engine features (attachments, encryption, flatten, metadata, PDF/A-UA, syntax validation) + +When a feature applies to multiple endpoints, it MUST be a shared partial. Never duplicate content across pages. Import the partial instead. + +## Admonitions + +Use Docusaurus admonitions for callouts: + +```mdx +:::info +Informational note about behavior or context. +::: + +:::warning +Important caveat or potential pitfall. +::: + +:::danger +Breaking behavior, data loss risk, or critical limitation. +::: + +:::tip +Helpful suggestion or best practice. +::: +``` + +Reserve `:::danger` for genuinely dangerous situations. Use `:::info` for most callouts. + +## Sidebar Updates + +When adding a new page, update `sidebars.js`: + +- API endpoints must include `className: "sidebar-method-post"` (or `-get`, `-head`) for the HTTP method badge. +- Place the page in the correct category following the existing order. +- Use `type: "doc"` with the document `id` matching the frontmatter. + +## Versioning + +The site supports versioned documentation (`versioned_docs/`, `versions.json`). Current docs live in `docs/`. Don't modify versioned docs unless explicitly asked. Changes to `docs/` apply to the current (next) version only. diff --git a/docs/configuration.mdx b/docs/configuration.mdx index 1a299b50..ea750867 100644 --- a/docs/configuration.mdx +++ b/docs/configuration.mdx @@ -368,55 +368,96 @@ The following flag allows you to hide the startup banner with: ## Docker Image +The examples below use the full image (`gotenberg/gotenberg:8`). Replace the base image tag to match your variant +(`:8-chromium`, `:8-libreoffice`). See the [installation guide](/docs/getting-started/installation#image-variants) for +available variants and their capabilities. + ### Fonts -The default Docker image is pre-packaged with an extensive assortment of fonts, including Asian ones. If your application -requires additional or specific fonts not included in this collection, you'll need to construct a tailored Docker image -to incorporate those fonts. +Since _8.30.0_, the font stack has been simplified from 30+ packages down to 8, covering Latin, Greek, Cyrillic, CJK, +and most world scripts through Noto, plus color emoji. + +| Package | Coverage | +| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `fonts-noto-core` | Arabic, Bengali, Devanagari, Ethiopic, Georgian, Gujarati, Gurmukhi, Hebrew, Kannada, Khmer, Lao, Malayalam, Myanmar, Sinhala, Tamil, Telugu, Thai, and more | +| `fonts-noto-cjk` | Chinese, Japanese, Korean | +| `fonts-noto-color-emoji` | Color emoji | +| `fonts-dejavu` | Latin, Greek, Cyrillic | +| `fonts-crosextra-carlito` | Metric-compatible with Calibri | +| `fonts-crosextra-caladea` | Metric-compatible with Cambria | +| `fonts-liberation` | Metric-compatible with Arial, Times New Roman, Courier New | +| `fonts-liberation2` | Updated Liberation metrics | + +Microsoft Core Fonts (`ttf-mscorefonts-installer`) are not shipped due to licensing constraints. The image includes +metric-compatible replacements instead: Carlito for Calibri, Caladea for Cambria, and Liberation for Arial, Times New +Roman, and Courier New. These preserve document layout in most cases. -**Via .tff files** +#### Installing Additional Fonts + +Build a custom Dockerfile to add fonts. Three common scenarios: + +**Microsoft Core Fonts** (you accept the [Microsoft EULA](https://corefonts.sourceforge.net/eula.htm)): ```docker FROM gotenberg/gotenberg:8 USER root -COPY /local/path/to/{font}.ttf /usr/local/share/fonts/{font}.ttf +RUN echo "ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true" | debconf-set-selections \ + && apt-get update -qq \ + && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends ttf-mscorefonts-installer \ + && rm -rf /var/lib/apt/lists/* USER gotenberg ``` -Or, if you have many fonts: +**Specialized script fonts** for richer glyph sets, better hinting, or traditional typefaces beyond the basic Noto +coverage: + +| Script | Package | +| :----------------- | :--------------------- | +| Arabic (Naskh) | `fonts-hosny-amiri` | +| Bengali | `fonts-beng` | +| Devanagari (Hindi) | `fonts-sarai` | +| Ethiopic | `fonts-sil-abyssinica` | +| Gujarati | `fonts-samyak-gujr` | +| Gurmukhi (Punjabi) | `fonts-lohit-guru` | +| Hebrew | `culmus` | +| Kannada | `fonts-lohit-knda` | +| Malayalam | `fonts-samyak-mlym` | +| Myanmar | `fonts-sil-padauk` | +| Sinhala | `fonts-lklug-sinhala` | +| Tamil | `fonts-samyak-taml` | +| Telugu | `fonts-telu` | +| Thai | `fonts-thai-tlwg` | ```docker FROM gotenberg/gotenberg:8 USER root -COPY /local/path/to/fonts/* /usr/local/share/fonts/ +RUN apt-get update -qq \ + && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends \ + fonts-hosny-amiri \ + fonts-thai-tlwg \ + && rm -rf /var/lib/apt/lists/* USER gotenberg ``` ---- - -**Via .deb packages** +**Custom .ttf files** from your own collection: ```docker FROM gotenberg/gotenberg:8 USER root -RUN DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends my-fonts-package +COPY /local/path/to/fonts/* /usr/local/share/fonts/ USER gotenberg ``` ---- - -**Via mounted volumes** - -You could also mount a volume containing your fonts to _/usr/local/share/fonts/_ as suggested in this +Alternatively, mount a volume to `/usr/local/share/fonts/` at runtime as described in this [comment](https://github.com/gotenberg/gotenberg/issues/602#issue-1580360200). ### Ownership diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index 3f16aed9..3854aa84 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -38,6 +38,35 @@ By default, published ports are accessible from the outside world. Bind to local docker run --rm -p "127.0.0.1:3000:3000" gotenberg/gotenberg:8 ``` +## Image Variants + +Gotenberg ships three image variants: + +| Image | Size | Includes | +| :---------------------------------- | :----------- | :--------------------------------------------------------------------------- | +| `gotenberg/gotenberg:8` | Full | Chromium, LibreOffice, and PDF Engines. | +| `gotenberg/gotenberg:8-chromium` | ~30% smaller | Chromium and PDF Engines. No office document conversion. | +| `gotenberg/gotenberg:8-libreoffice` | ~40% smaller | LibreOffice and PDF Engines. No URL/HTML/Markdown conversion or screenshots. | + +All variants include PDF Engines (merge, split, encrypt, watermark, metadata, bookmarks, attachments, etc.). + +### Feature Availability + +| Feature | Full | Chromium | LibreOffice | +| :----------------------------------------------------- | :--: | :------: | :---------: | +| URL / HTML / Markdown to PDF | ✅ | ✅ | ❌ | +| Screenshots | ✅ | ✅ | ❌ | +| Office document conversion (.docx, .xlsx, .pptx, etc.) | ✅ | ❌ | ✅ | +| Merge, split, rotate, flatten PDFs | ✅ | ✅ | ✅ | +| Encrypt, watermark, stamp PDFs | ✅ | ✅ | ✅ | +| Read/write metadata & bookmarks | ✅ | ✅ | ✅ | +| File attachments | ✅ | ✅ | ✅ | +| PDF/A & PDF/UA conversion | ✅ | ❌ | ✅ | +| Webhooks & async processing | ✅ | ✅ | ✅ | +| Download from remote URLs | ✅ | ✅ | ✅ | + +Requesting an unavailable feature returns an error. + ## Docker Compose ```yaml title="compose.yaml" @@ -84,6 +113,8 @@ Allocate at least 512Mi of memory and 0.2 CPU. A community-maintained Helm chart ``` gotenberg/gotenberg:8-cloudrun +gotenberg/gotenberg:8-chromium-cloudrun +gotenberg/gotenberg:8-libreoffice-cloudrun ``` Preconfigured for Cloud Run: @@ -101,6 +132,8 @@ Available on `linux/amd64` and `linux/arm64`: ``` gotenberg/gotenberg:8-aws-lambda +gotenberg/gotenberg:8-chromium-aws-lambda +gotenberg/gotenberg:8-libreoffice-aws-lambda ``` Preconfigured for AWS Lambda: diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx index 40a4adef..90936ed7 100644 --- a/docs/troubleshooting.mdx +++ b/docs/troubleshooting.mdx @@ -50,7 +50,8 @@ Issue not listed here? Check [GitHub issues](https://github.com/gotenberg/gotenb ### Layout & Font Shifts -- **Missing Fonts:** LibreOffice relies on installed system fonts to calculate page breaks and layout. If your document uses a font not present in the container, LibreOffice will substitute it, causing shifted layouts. You must install the required fonts via a custom `Dockerfile` (see [Fonts configuration](configuration#fonts)). +- **Missing Fonts:** LibreOffice relies on installed system fonts to calculate page breaks and layout. If your document uses a font not present in the container, LibreOffice will substitute it, causing shifted layouts. Install the required fonts via a custom Dockerfile (see [Fonts configuration](configuration#fonts)). +- **After upgrading to 8.30.0:** The font stack was simplified from 30+ packages to 8. Documents relying on Microsoft Core Fonts (Arial, Times New Roman, Calibri) now use metric-compatible replacements. If you notice layout differences after upgrading, install `ttf-mscorefonts-installer` or the specific script fonts your documents need (see [Fonts configuration](configuration#installing-additional-fonts)). ### Server Errors (500) diff --git a/docs/webhook-download.mdx b/docs/webhook-download.mdx index 9c2f8169..39e06031 100644 --- a/docs/webhook-download.mdx +++ b/docs/webhook-download.mdx @@ -34,8 +34,9 @@ See the [Webhook module configuration](/docs/configuration#webhook) for retries, name: "Gotenberg-Webhook-Error-Url", type: "string", defaultValue: "None", - description: "The callback URL to use if the conversion fails.", - required: true, + description: + "Deprecated. The callback URL to use if the conversion fails. Not required when Gotenberg-Webhook-Events-Url is set.", + required: false, }, { name: "Gotenberg-Webhook-Method", @@ -69,7 +70,7 @@ See the [Webhook module configuration](/docs/configuration#webhook) for retries, curl \\ --request POST http://localhost:3000/forms/chromium/convert/url \\ --header 'Gotenberg-Webhook-Url: https://my.webhook/success' \\ ---header 'Gotenberg-Webhook-Error-Url: https://my.webhook/error' \\ +--header 'Gotenberg-Webhook-Events-Url: https://my.webhook/events' \\ --header 'Gotenberg-Webhook-Extra-Http-Headers: {"Authorization": "Bearer 123"}' \\ --form url=https://my.url `} diff --git a/src/README.md b/src/README.md new file mode 100644 index 00000000..05a1dd8f --- /dev/null +++ b/src/README.md @@ -0,0 +1,101 @@ +# Site Design and Components + +Guidelines for modifying site design, React components, styles, or layout: CSS, theme, homepage, `.js`/`.css` files. + +## Technology Stack + +- **Framework:** Docusaurus 3.8.1 (React 18) +- **Styling:** CSS Modules (`.module.css`) for components, global CSS (`src/css/custom.css`) for theme overrides +- **Fonts:** Inter (body, headings), JetBrains Mono (code), loaded via Google Fonts +- **Icons:** Inline SVGs in React components (no icon library) +- **Images:** `@docusaurus/plugin-ideal-image` for optimized images + +## Design System + +### Colors + +| Token | Value | Usage | +| ------------------------------- | --------- | ----------------------------- | +| `--ifm-color-primary` | `#008ae6` | Links, accents, primary CTA | +| `--ifm-heading-color` | `#0f172a` | H1 headings | +| `--ifm-color-content` | `#334155` | Body text | +| `--ifm-color-content-secondary` | `#64748b` | Secondary text, sidebar links | +| `--ifm-border-color` | `#e2e8f0` | Borders, dividers | + +HTTP method badge colors: + +- POST: `#49cc90` (green) +- GET: `#61affe` (blue) +- PUT: `#fca130` (orange) +- DELETE: `#f93e3e` (red) +- HEAD: `#9061f9` (purple) + +### Typography + +- H1: 3rem, weight 900, letter-spacing -0.03em, blue bottom border +- H2: 1.8rem, weight 800, letter-spacing -0.02em, gray bottom border +- H3: 1.4rem, weight 700, blue left border with padding +- Body: 1.05rem, line-height 1.75 +- Code: 0.85em, weight 500, subtle gray background + +### Spacing and Layout + +- Max content width: 840px (`.theme-doc-markdown`) +- Container width: 1366px +- Navbar height: 4rem +- Light mode only (dark mode switch is disabled) + +## Component Architecture + +### Homepage (`src/components/Homepage.js`) + +A standalone React component with CSS Modules (`Homepage.module.css`). Contains: + +- Hero section with logo, tagline, and CTA buttons +- Community stats strip (Docker pulls, GitHub stars, license) +- Feature blocks with `SimpleTerminal` code previews +- Final CTA section + +The `SimpleTerminal` component renders syntax-highlighted bash commands with a macOS-style window chrome (red/yellow/green dots). + +### ApiEndpoint (`src/components/documentation/ApiEndpoint.js`) + +The core documentation component. Renders API endpoint information with: + +- Method badge + path header +- Collapsible parameter lists (headers, form fields, form files) +- cURL example via Docusaurus `` +- Tabbed response display via Docusaurus `` + +This component has its own CSS Module (`ApiEndpoint.module.css`). + +### Sponsors (`src/components/documentation/Sponsors.js`) + +Renders sponsor logos at the bottom of documentation pages. + +## Theme Overrides + +- `src/theme/DocSidebar/index.js`: Custom sidebar with HTTP method badges via CSS pseudo-elements +- Sidebar badges are implemented purely in CSS using `::before` pseudo-elements on `.sidebar-method-*` classes + +## CSS Conventions + +- Use CSS custom properties (`--ifm-*`) for Docusaurus theme values +- Use CSS Modules for component-scoped styles +- Use `src/css/custom.css` only for global overrides (admonitions, sidebar, footer, typography) +- Transitions: `0.2s ease` for interactive elements, `0.3s cubic-bezier(0.4, 0, 0.2, 1)` for larger animations +- Hover effects: subtle `translateY(-1px)` lift with colored box-shadow +- Use `clsx` for conditional class composition in React components + +## Docusaurus Integration + +- Respect Docusaurus's Infima CSS framework. Override with specificity, not `!important` (except documented exceptions). +- Use `@docusaurus/Link` for internal navigation, not `` tags +- Use `useBaseUrl` for static asset paths +- Swizzled components live in `src/theme/`. Be cautious when upgrading Docusaurus. + +## Responsive Design + +- Tables switch to horizontal scroll below 1280px +- Content padding adjusts at 996px and 1400px breakpoints +- Homepage uses Docusaurus grid system (`col col--6`, `row`, `container`) diff --git a/src/components/Homepage.js b/src/components/Homepage.js index cd46bec4..6f219e3e 100644 --- a/src/components/Homepage.js +++ b/src/components/Homepage.js @@ -185,7 +185,6 @@ export default function Homepage() { }]' # 2. Tell Gotenberg where to upload the result (S3 PUT) \\ --header 'Gotenberg-Webhook-Url: https://my-bucket.s3.amazonaws.com/out.pdf?Start=...' \\ ---header 'Gotenberg-Webhook-Error-Url: https://my-api.com/errors' \\ --header 'Gotenberg-Webhook-Method: PUT' \\ # 3. Get notified when it's done \\ --header 'Gotenberg-Webhook-Events-Url: https://my-api.com/events'