Embed a PDF inline in a page

Print the HTML fragment that shows a PDF in the installed viewer: a lazily loaded frame whose address is derived from the page’s own location (so one page works at the site root, under a project base and under a staging preview), plus plain open and download links that work without it.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

pdf-inline-viewer

Show a published PDF inside a generated page — search, scroll, jump to page, print and download — with the pinned pdf.js viewer the site build installs. Which two Tools do it, the publication-gate rule that decides whether a page may embed a document at all, why the viewer opens only allowlisted hosts, and the three pdf.js behaviours that were measured rather than assumed. Read before putting a PDF on a page, before bumping the pdf.js pin, and when an embedded viewer shows an empty frame.

Source: cat-harness/platform-ui/skills/platform-ui/pdf-inline-viewer.md.

Also satisfied by: pdf-viewer-install.

The skill declares no I/O contract (schemas/skills/pdf-inline-viewer/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inspecTextyesOne JSON object: src (the PDF’s URL, which must fall under a prefix pdf-viewer-install was given, or the viewer refuses it on screen), title (what the document is; the frame’s accessible name), route (a regular expression over the page’s pathname whose group 1 is the site root — the folio-mount.ts convention) and optionally page (open at this 1-based page). On stdin because a title and a regular expression are free text.string · A short single-line human string. Not admissible as a command-line argument.
outfragmentTextThe HTML fragment on stdout. TypeScript callers import embed from the module that implements this Tool instead.string · A short single-line human string. Not admissible as a command-line argument.

Processes and tasks

No process step names a skill this Tool satisfies.

How it is deployed and reached

  • Command line. From the repository root: bun run cat pdf:viewer --embed. cat pdf:viewer runs bun run cat-harness-tools/scripts/pdf-viewer.ts (declared in cat-harness-tools/package.json).
  • GitHub Actions. 2 workflow line(s) run its command:
workflowline
.github/workflows/docs-site.yml640bun run cat-harness-tools/scripts/pdf-viewer.ts --site ./_site
.github/workflows/feature-staging.yml1267bun run cat-harness-tools/scripts/pdf-viewer.ts --site ./_site

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkno
when to choose it
whenA generated page should let a reader search, page through, print or download a PDF without leaving it. Only for a document whose publication gates permit linking it: an embed is a link that also renders.
limitsIt renders PDFs only. It cannot tell whether the site it lands on had the viewer installed; when it did not, or the page is off the route, the frame says so and the plain links still work.
costNothing until the reader scrolls to it; then the viewer and worker (~3 MB, cached after the first) and the PDF itself.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/cat-harness/tools/pdf-viewer-embed.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/cat-harness/cat-harness.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pdf-viewer-embed.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/cat-harness/cat-harness.jsonld",
  "name": "pdf-viewer-embed",
  "title": "Embed a PDF inline in a page",
  "description": "Print the HTML fragment that shows a PDF in the installed viewer: a lazily loaded frame whose address is derived from the page's own location (so one page works at the site root, under a project base and under a staging preview), plus plain open and download links that work without it.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run cat pdf:viewer --embed"
  },
  "io": {
    "inputs": [
      {
        "name": "spec",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "One JSON object: `src` (the PDF's URL, which must fall under a prefix `pdf-viewer-install` was given, or the viewer refuses it on screen), `title` (what the document is; the frame's accessible name), `route` (a regular expression over the page's pathname whose group 1 is the site root — the `folio-mount.ts` convention) and optionally `page` (open at this 1-based page). On stdin because a title and a regular expression are free text.",
        "required": true,
        "arg": {
          "stdin": true
        }
      }
    ],
    "outputs": [
      {
        "name": "fragment",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "The HTML fragment on stdout. TypeScript callers import `embed` from the module that implements this Tool instead."
      }
    ]
  },
  "satisfies": [
    "pdf-inline-viewer"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "A generated page should let a reader search, page through, print or download a PDF without leaving it. Only for a document whose publication gates permit linking it: an embed is a link that also renders.",
    "limits": "It renders PDFs only. It cannot tell whether the site it lands on had the viewer installed; when it did not, or the page is off the route, the frame says so and the plain links still work.",
    "cost": "Nothing until the reader scrolls to it; then the viewer and worker (~3 MB, cached after the first) and the PDF itself."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev