html-pdf

_schema_version	1
name	html-pdf
author	christina
skill-type	technique-skill
description	Use when asked to convert an HTML file to a PDF and open it. Do NOT use for non-HTML inputs, PDF editing, or page screenshots.
disable-model-invocation	true

html-pdf

Convert an HTML file to a PDF and open it in the system default web browser.

Rendering goes through headless Chromium (Playwright), so CSS, web fonts, the page's dark/light theme, and any JavaScript run exactly as in a real browser. The work is a deterministic facade script (scripts/html_to_pdf.py); this skill decides the input/output paths and relays the result.

Engine & modes (reference)

Aspect	Detail
Engine	Headless Chromium via Playwright (provisioned by the plugin venv + custom_bootstrap chromium install).
Default mode	Single-page -- PDF page sized to the content's real height, so there are no A4 pagination blank-gaps. Suits posters and diagram pages.
--a4	Paginates to A4 and honors the page's own @media print rules (white background, page breaks).
Default output	<input>.pdf next to the input file; pass an explicit second argument to override.
--scale	Fraction (0.8) or percent (80% / 80). Range 10%-200%, default 100%. When the user says "scale it to 80%", pass --scale 80%.
Invocation	uv run --project "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/skills/html-pdf/scripts/html_to_pdf.py" <input.html> [output.pdf] [--scale 80%] [--a4]

Technique

The load-bearing contract; the table above is reference detail the steps draw on.

technique_skill:
  _schema_version: "1"
  trigger_model: user-only
  identity: Convert an HTML file to a PDF via headless Chromium and open it in the default browser.

  scope:
    covers:
      - rendering a local .html file to a .pdf with full CSS/JS fidelity
      - opening the resulting PDF in the system default web browser
      - choosing single-page (poster) vs A4-paginated output
    excludes:
      - non-HTML inputs (markdown, images, URLs) -- this takes a local HTML file
      - editing, merging, or annotating existing PDFs
      - capturing a screenshot/PNG of a page (this produces a PDF)

  techniques:
    - id: convert
      name: Convert an HTML file to a PDF and open it
      keywords: [html to pdf, convert html, render pdf, html pdf, export pdf, print to pdf, open pdf, scale, scale to 80%, percent, shrink, zoom]
      goal: Render a local HTML file to a PDF via headless Chromium at the chosen mode and scale, then open it in the default browser.
      steps:
        - n: 1
          action: Resolve the input HTML file
          detail: >-
            Take the .html path the user referenced and confirm it exists. The input must be
            a local HTML file. For best results it should be self-contained -- a page that
            pulls in sibling files or local-disk asset paths will convert but render broken.
        - n: 2
          action: Decide the output path, mode, and scale
          detail: >-
            Default output is <input>.pdf beside the input; pass an explicit second argument to
            override. Default rendering is single-page (no blank gaps), which suits posters and
            diagram pages. Use --a4 only when the user wants a paginated, print-style document.
            If the user asks to scale ("scale it to 80%", "make it 80%", "0.8"), pass --scale 80%
            -- it shrinks/grows the whole rendering; in single-page mode the page resizes with it
            so there is no surrounding whitespace.
        - n: 3
          action: Run the converter
          tool: ${CLAUDE_PLUGIN_ROOT}/skills/html-pdf/scripts/html_to_pdf.py
          precondition: >-
            Before running, confirm bootstrap has provisioned html-pdf: if
            ~/.claude/plugins/data/plugins-kit/awesome-kit/bootstrap.log is missing, tell the user
            "the bootstrap plugin hasn't provisioned awesome-kit's html-pdf -- install/enable
            plugins-kit:bootstrap and start a new session" and stop (the venv + Chromium aren't set up).
          detail: 'uv run --project "${CLAUDE_PLUGIN_ROOT}" python "${CLAUDE_PLUGIN_ROOT}/skills/html-pdf/scripts/html_to_pdf.py" "<input.html>" ["<output.pdf>"] [--scale 80%] [--a4]'
        - n: 4
          action: Relay the result
          detail: >-
            The script prints `PDF <path>` then `OPENED in default browser` (or `OPEN-FAILED ...`).
            It opens the PDF in the default browser automatically; pass --no-open to skip that.
            Give the user the output path and confirm it opened.
      output_template: |
        Converted -> <output.pdf> (opened in your default browser).
      gotchas:
        - id: needs_chromium
          keywords: [playwright, chromium, browser not installed, executable doesn't exist]
          gotcha: >-
            Requires the Chromium browser binary. Bootstrap installs it (custom_bootstrap.py). If
            the converter errors that the browser is missing, install it manually:
            `uv run --project "${CLAUDE_PLUGIN_ROOT}" python -m playwright install chromium`.
        - id: self_contained_only
          keywords: [broken page, missing css, external assets, fragment, relative paths]
          gotcha: Only self-contained HTML renders correctly. External stylesheets/scripts over the network load, but sibling-file and local-disk asset references render broken in the PDF.
        - id: single_page_default
          keywords: [blank space, blank pages, pagination gaps, a4, poster]
          gotcha: >-
            Default single-page mode avoids the blank gaps that A4 pagination creates when tall
            `break-inside: avoid` blocks jump to the next page. Reach for --a4 only when a true
            paginated/printable document is wanted; expect some bottom-of-page whitespace then.
        - id: opens_browser_not_reader
          keywords: [opened in pdf app, default handler, wrong app, system default browser]
          gotcha: >-
            On Windows the default *web browser* is resolved from the registry so the PDF opens in
            the browser, not the .pdf-associated app. If no browser resolves, it falls back to the
            stdlib opener, which may use the OS default handler instead.
        - id: overwrites_output
          keywords: [overwrite, existing pdf, clobber]
          gotcha: The output path is overwritten without prompting. Use a distinct output name to keep a prior PDF.