Skip to content
Skills Library
Documents & office · Conversion & formats

render-pdf

/render-pdf

This skill should be used when a web page, a URL or an HTML file has to become a PDF with bidi2pdf's command line, including a PDF of a page's screen view, dark mode or mobile layout, a tagged (accessible) PDF, or a PDF piped through stdin/stdout. Covers the order of commands, the waits, reading the JSON result and the exit codes.

Repository
bidi2pdf ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
7
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

This skill should be used when a web page, a URL or an HTML file has to become a PDF with bidi2pdf's command line, including a PDF of a page's screen view, dark mode or mobile layout, a tagged (accessible) PDF, or a PDF piped through stdin/stdout. Covers the order of commands, the waits, reading the JSON result and the exit codes.

Triggers from the description

s command line, including a PDF of a page
Original author description

This skill should be used when a web page, a URL or an HTML file has to become a PDF with bidi2pdf's command line, including a PDF of a page's screen view, dark mode or mobile layout, a tagged (accessible) PDF, or a PDF piped through stdin/stdout. Covers the order of commands, the waits, reading the JSON result and the exit codes.

How it works

  1. Ground rules
  2. 1. Preflight
  3. 2. Render
  4. 3. Page size, margins, screen view, mobile layout
  5. 4. Read the result, not the logs
  6. 5. When it fails or looks wrong
Original SKILL.md headings · 164 lines, 1,227 words
SKILL.md preview
---
name: render-pdf
description: This skill should be used when a web page, a URL or an HTML file has to become a PDF with bidi2pdf's command line, including a PDF of a page's screen view, dark mode or mobile layout, a tagged (accessible) PDF, or a PDF piped through stdin/stdout. Covers the order of commands, the waits, reading the JSON result and the exit codes.
---

# Render a PDF with the bidi2pdf CLI

bidi2pdf prints a page in a real Chrome over WebDriver BiDi. This skill is the order of work and the
pitfalls; the exact options are in `bidi2pdf help render`, the exact result shape in
`bidi2pdf schema render`. Read those instead of guessing an option.

**Does not:** scrape page content or automate a site (log in, click through). bidi2pdf is a
renderer; for a page that needs steps before printing, write a recipe (the `pdf-recipe` skill).

## Ground rules

- **bidi2pdf is the renderer.** If it fails, report its `error.code`, `error.hint` and exit code;
  never make the PDF or screenshot another way (Chrome's own print-to-PDF, another PDF engine).
- **Install nothing unasked.** Name what is missing and suggest a way (the `render-pdf` skill's
  preflight); run nothing that changes the system without the user's yes.
- **bidi2pdf's results first.** Read its `--json` result instead of inspecting the PDF with other
  tools.

## 1. Preflight

```bash
bidi2pdf version --json
```

One call answers three questions: is bidi2pdf there at all, which version (`bidi2pdf`), and whether
`pages` will be filled (`pdf_reader` is `null` without that gem). `--media`, `--color_scheme` and
`--reduced_motion`, and a clean stdout for `--json` and `--output -`, need 0.1.23 or later. If
`bidi2pdf help render` does not list an option, the installed gem is older - say so instead of
working around it.

**When bidi2pdf is missing**, look first, install nothing yet, and suggest the lightest way that fits:

```bash
ruby -v; docker info --format '{{.ServerVersion}}'; command -v chromium chromium-browser google-chrome
```

1. **Docker answers** (`docker info` prints a server version, not an error - an installed client
   without a reachable daemon or socket permission does not count): nothing to install, the image
   has Ruby, Chromium and pdf-reader. Inside a container that uses the host's Docker, `-v` mounts
   a path of the host, not of the container.
2. **Ruby 3.4 or later is there:** `gem install bidi2pdf`, plus a browser if none was found.
   `pdf-reader` only when the page count is needed.
3. **No Ruby, or an older one:** a distribution's Ruby is too old (Debian 12 ships 3.1, Debian 13
   3.3, Ubuntu 24.04 3.2 - and a `node` image is Debian). Homebrew's `ruby` on macOS, a version
   manager (`mise`, `rbenv`) elsewhere - or option 1, which needs no Ruby at all.

```bash
# 1. Docker: no install
docker run --rm -v "$PWD:/reports" dieters877565/bidi2pdf:main-slim \
  bidi2pdf render --url https://example.com --output /reports/example.pdf --json
# 2. Ruby 3.4+
gem install bidi2pdf
gem install pdf-reader    # optional: fills "pages"
# Browser on Debian, or in a Debian-based container (the packaged driver also works on ARM)
sudo apt-get install -y chromium chromium-driver
# Ruby on macOS (Google Chrome, if installed, is the browser)
brew install ruby
```

bidi2pdf fetches a matching chromedriver itself, which may fail on ARM Linux - there use the
packaged `chromium-driver`. Ubuntu's `chromium` is a snap that does not run in a container: use a
shared browser there (the `remote-chrome` skill).

**Show the user the commands that fit and run them only after a yes** - they change the system.

Where Chrome runs:

- **A shared browser** (a chromedriver container): pass `--remote-browser-url
  http://<host>:3000/session` to every command. The `remote-chrome` skill sets one up.
- **Local**: bidi2pdf starts chromedriver itself; Chrome or Chromium must be installed. Inside a
  container add `--no-sandbox` (or set `DISABLE_CHROME_SANDBOX=true`).

## 2. Render

```bash
bidi2pdf render --url https://example.com/invoice/123 --output invoice.pdf \
  --wait-network-idle --json --manifest invoice.manifest.json
```

- **Waits.** Without one, bidi2pdf prints as soon as the page's load event fired.
  `--wait-network-idle` waits for late requests (lazy images, fetched data).
  `--wait-window-loaded` waits until the page's **own script** sets `window.loaded = true` - use it
  for Paged.js or any page that finishes rendering itself, never for a page that does not set it:
  that one waits the whole `--default-timeout` (60 s) and fails with `COMMAND_TIMEOUT`.
- **Input.** `--url`, `--html-file`, or `--stdin` for HTML on standard input - exactly one.
- **Output.** `--output file.pdf`; `--output -` writes the PDF bytes to stdout and nothing else (it
  cannot be combined with `--json`).
- **`--manifest`** records what was rendered with which options, to reproduce or debug it later
  (cookie values and secret headers are left out).
- **Cookies, headers, basic auth:** `--cookie name=value`, `--header Name=value`, `--auth user:pass`.

```bash
cat page.html | bidi2pdf render --stdin --output - > page.pdf
```

## 3. Page size, margins, screen view, mobile layout

All sizes are **centimetres**: `--page-width`/`--page-height` (default US Letter, 21.59 x 27.94),
`--margin-top/-bottom/-left/-right`. Chrome's own default margin is 1 cm a side.

By default Chrome prints with the page's **print stylesheet**. To print what the screen shows:

```bash
bidi2pdf render --url https://example.com --output screen.pdf --media screen
bidi2pdf render --url https://example.com --output dark.pdf --media screen --color_scheme dark
```

A **mobile layout** needs a narrow page. A printed page is laid out between its side margins, at
96 / 2.54 = about 37.8 CSS px per cm, so set the side margins yourself:

```bash
bidi2pdf render --url https://example.com --output phone.pdf --media screen \
  --page-width 9.525 --page-height 20 --margin-left 0 --margin-right 0
```

9.525 cm without side margins is 360 px; 8.467 cm is 320 px. With Chrome's default 1 cm margins a
9.5 cm page is only about 283 px wide and may hit a smaller breakpoint than intended.

For an accessible PDF add `--generate-tagged-pdf` (and `--generate-document-outline` for bookmarks).

## 4. Read the result, not the logs

With `--json`, stdout carries exactly one JSON document; logs go to stderr. Check `ok`, then:

- `pages`, `bytes`, `sha256` of the PDF. `pages` is `null` without `pdf-reader`, with a warning:
  report it that way, or ask before installing that gem - no other PDF tool for a page count.
- `navigation.final_url` - a redirect to a login page answers 200 and prints perfectly. (A status
  of 400 or more fails the render instead.)
- `network_failures` and `console` even when `ok` is true: a missing image still gives a PDF.
- On failure `error.code`, `error.retryable` and `error.hint`. Retry only when `retryable` is true.

The exit code says the same without parsing:

| Code | Exit | Meaning |
|---|---|---|
| `INVALID_PRINT_OPTION` | 2 | an option value bidi2pdf refuses - fix the command |
| `MISSING_INPUT` | 2 | none of --url, --html-file, --stdin given |
| `DNS_ERROR` | 3 | the host does not resolve **from the browser's machine** |
| `NAVIGATION_TIMEOUT` | 3 | the page did not load in time |
| `NAVIGATION_NOT_FOUND` | 3 | the URL answered 404 |
| `NAVIGATION_FAILED` | 3 | the URL answered another 4xx/5xx, or the connection failed |
| `BROWSER_LAUNCH_FAILED` | 3 | no Chrome/chromedriver - see section 1 |
| `COMMAND_TIMEOUT` | 3 | a wait never finished (often `--wait-window-loaded`) |
| `PDF_GENERATION_FAILED` | 6 | Chrome could not print |
| `OUTPUT_WRITE_FAILED` | 6 | the output path cannot be written |

The full list: `bidi2pdf schema render` (the `error` object) and README "Exit codes".

`--json-stream` writes one progress event per line to stderr while it runs (`bidi2pdf schema
event`), for a long render a user should see move.

## 5. When it fails or looks wrong

Only then, with the same options as the render:

```bash
bidi2pdf diagnose --url https://example.com/invoice/123 --json --screenshot seen.png
```

`diagnose` loads the page like `render` and prints no PDF; `console`, `network_failures`,
`fonts.status`, `print_media` and `paged_js` usually name the cause. The checklist: the
`diagnose-pdf` skill.

Versions

The database has no other skills named render-pdf.

Database snapshot: 13.11.2026 · package version 03ccaa8112a7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100shotlane
    Screenshot any public web page, read pages as clean Markdown (JavaScript rendered), and render HTML or URLs to PDF using the Shotlane API. Use when the user wants to see what a website looks like, check a deployed page or layout on desktop/mobile, capture a page or element as an…
  • 100hk-pdf-export
    Turn an HTML page, or content that has to become one first, into a PDF in the house design and check nothing was lost. Triggers on: 'make a PDF of this', 'export this to PDF', 'can I print this', or /hk-pdf-export.
  • 100pdf
    This skill should be used when the user wants a PDF to share with people who can't open the original, such as "/fathom:pdf", "make a PDF of this view", "export this artifact to PDF", "turn this into a one-pager", "I need to send this to someone without Claude", or "print this…
  • 100accessible-pdf
    Make a LaTeX document produce accessible tagged PDFs (PDF/UA-1, PDF/A-2b). Creates a non-destructive copy and Makefile target. Use when the user needs accessible or tagged PDFs.
  • 100render-html
    Render an ARIS Markdown / JSON artifact (IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN, research-wiki state, etc.) into a single-file HTML view designed for human reading. Use when the user says \"Render HTML\", \"Here's a copy. HTML Report\", \"render html\", \"make this…
  • 100render-html
    Render an ARIS Markdown / JSON artifact (IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN, research-wiki state, etc.) into a single-file HTML view designed for human reading. Use when the user says \"渲染 HTML\", \"出一份 HTML 报告\", \"render html\", \"make this readable\",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.