Scan every page of a built IG site in a headless browser for markup shown as text
The checkout script ig-site:page-render-qa, the IG site build’s last final step: it serves the built site locally, opens the root pages and the artefact pages (not the JSON views, mappings views or redirect stubs) in headless Chromium, waits for each to draw, and lists every text block that shows markdown as text (bold, list markers, links, images, code, headings, tables, HTML tags), code and preformatted text left out. It writes assets/fhir-qa/page-render.json and the script the QA report’s “Page scan” panel draws it with. It reports and never fails the build: without a browser it writes why.
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.
ig-build-pipeline
The bare FHIR IG pipeline — FSH to SUSHI to the IG Publisher to a pages branch, with no pre-processing and no post-processing. What this layer runs, what it emits, and the list of things it deliberately refuses to know about. Owns the AST cache lifecycle: an IG site is built from the AST on its cache branch, the publish refuses a stale one, and the reusable ig-ast-refresh.yml is the one writer. Owns what an IG reader may read: contentTypes.ig.include in the repository’s index.config.json, and the legacy warning for a repository that declares none. Read before adding anything to fhir-harness, before onboarding, converting or changing the workflows of an IG repository, and before publishing an IG site.
Source: fhir-harness/skills/fhir-ig-base/ig-build-pipeline.md.
Also satisfied by: build-ig-site, fhir-core, ig-artifact-jsonld, ig-ast-refresh, ig-index-build, ig-pages, ig-publisher-i18n, ig-repo-site, ig-site-data, ingest-ig-menu, jsonld-vocabularies, logical-model-schemas, stage-ig-sites, strip-library-binaries, strip-library-content, terminology-index, valueset-schemas.
The skill declares no I/O contract (schemas/skills/ig-build-pipeline/{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.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | site | RepoPath | yes | The built site directory. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | limit | Count | Scan at most this many pages. | integer · A non-negative count — how many of something, or how many to show. Zero is a real answer. | |
| in | concurrency | Count | Pages open at once; 4 by default. | integer · A non-negative count — how many of something, or how many to show. Zero is a real answer. | |
| out | findings | Count | Text blocks that show markup as text. | integer · A non-negative count — how many of something, or how many to show. Zero is a real answer. |
Processes and tasks
Steps this Tool can carry out, because each names a skill it satisfies:
| process | step | lane | via skill |
|---|---|---|---|
| An IG site, built from the AST on its cache branch | Restore and judge the cached AST | Site build (agent, stage-local) | ig-build-pipeline |
| An IG site, built from the AST on its cache branch | Build and publish the site from the AST | Site build (agent, stage-local) | ig-build-pipeline |
| An IG site, built from the AST on its cache branch | Dispatch AST refresh | Publication manager (owner, or the agent the owner delegates to) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Build each IG’s artefact index | Host docs site build (CI runner) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Generate each IG instance’s artefact pages | Host docs site build (CI runner) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Clone each IG at its recorded commit and stage it | Host docs site build (CI runner) | ig-build-pipeline |
How it is deployed and reached
- Command line. From the repository root:
bun run fhir-harness/scripts/ig-page-render-qa.ts. - GitHub Actions. No workflow in this checkout runs its command.
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun |
| network | no |
| when to choose it | |
|---|---|
| when | After an IG site is built, so the QA report shows what its pages show a reader. |
| limits | Needs Playwright and Chromium; without them it records why and scans nothing. Pages that do not finish drawing in 15 s are listed as unfinished. |
| cost | About 20 s for 200 pages. |
What it is made of
| role | file | |
|---|---|---|
| definition | fhir-harness/tools/ig-page-render-qa/ig-page-render-qa.ts | |
| script | fhir-harness/scripts/ig-page-render-qa.ts |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/fhir-harness/tools/ig-page-render-qa.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/fhir-harness/fhir-harness.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/fhir-harness/tools/ig-page-render-qa.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
"name": "ig-page-render-qa",
"title": "Scan every page of a built IG site in a headless browser for markup shown as text",
"description": "The checkout script `ig-site:page-render-qa`, the IG site build's last final step: it serves the built site locally, opens the root pages and the artefact pages (not the JSON views, mappings views or redirect stubs) in headless Chromium, waits for each to draw, and lists every text block that shows markdown as text (bold, list markers, links, images, code, headings, tables, HTML tags), code and preformatted text left out. It writes `assets/fhir-qa/page-render.json` and the script the QA report's \"Page scan\" panel draws it with. It reports and never fails the build: without a browser it writes why.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run fhir-harness/scripts/ig-page-render-qa.ts"
},
"io": {
"inputs": [
{
"name": "site",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The built site directory.",
"required": true
},
{
"name": "limit",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
"description": "Scan at most this many pages.",
"required": false,
"arg": {
"flag": "--limit"
}
},
{
"name": "concurrency",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
"description": "Pages open at once; 4 by default.",
"required": false,
"arg": {
"flag": "--concurrency"
}
}
],
"outputs": [
{
"name": "findings",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
"description": "Text blocks that show markup as text."
}
]
},
"satisfies": [
"ig-build-pipeline"
],
"requirements": {
"runtime": [
"bun"
],
"network": false
},
"selection": {
"when": "After an IG site is built, so the QA report shows what its pages show a reader.",
"limits": "Needs Playwright and Chromium; without them it records why and scans nothing. Pages that do not finish drawing in 15 s are listed as unfinished.",
"cost": "About 20 s for 200 pages."
}
}