Generate an IG instance’s reader-facing pages from its artefact index

Write <instance>/docs/ — an index page, one page per artefact, a page per over-large category and per menu group — from fhir-artifact-index/index.json (and menu.json when ingested), styled by the template chrome an owning instance ingested. For an instance whose docs declare igSite it writes no index, menu or category pages — the IG site’s own replace them — and only a front-matter artifacts.md naming the Tool that drew it. build-ig-site renders an IG’s narrative pages from source; this Tool writes the artefact pages for every IG instance (stage-ig-sites copies them in).

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-page-render-qa, 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.

porttyperequireddescriptionconstraint
ininstanceRepoPathyesThe instance directory: holds fhir-artifact-index/ and receives docs/.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
insiteRepoPathWhere an instance declares a visualiser renderedBy: ig-pages, the Tool writes that visualiser’s route page. With this site directory it writes ONLY those route pages (<locale>/<harness>/<id>/ and, per instance, …/<instance>/) under it: not docs/, not the instance. Each opens the IG’s artefact index.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inlabelTextThe IG’s display name. The index carries only the package id, which stands in when this is absent.string · A short single-line human string. Not admissible as a command-line argument.
inchrome-ownerTextThe instance whose chrome.json styles the pages. Absent, the pages are unstyled and the build says so. The banner’s identity is always the index’s; a chrome ingested from another IG lends its tokens, never its status.string · A short single-line human string. Not admissible as a command-line argument.
insummaryFlagOpen the index page with the instance’s own declaration (harness_details.html with instance=), making it the instance’s landing page.boolean · A boolean switch — projects to a bare flag, with no value word
infull-pagesFlagDefault: each artefact page is a thin shell at the same address, with its JSON-LD node, the index node (artifact/index.jsonld) and the shared renderer assets/ig-artifact.js. With it: full pages, no JSON-LD.boolean · A boolean switch — projects to a bare flag, with no value word
injsonld-baseUrlThin pages only: the docs root’s published URL, so each node’s IRIs are absolute. Absent, they are relative to the node’s own file.string · format uri · An absolute http(s) URL
incompiled-dataRepoPathWhere a compiled index’s resource files are served, as a path from the docs root. . means each is served once at the docs root as <Type>-<id>.json, as the IG site does; a docs root beside the AST passes ../ast-data.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
incheckFlagWrite nothing; exit 1 when any page is stale or orphaned.boolean · A boolean switch — projects to a bare flag, with no value word
outpagesCountPages written; the menu and chrome are reported as present or COULD NOT DETERMINE, never silently absent.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:

processsteplanevia skill
An IG site, built from the AST on its cache branchRestore and judge the cached ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchBuild and publish the site from the ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchDispatch AST refreshPublication 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-docsBuild each IG’s artefact indexHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsGenerate each IG instance’s artefact pagesHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsClone each IG at its recorded commit and stage itHost 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/gen-ig-pages.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.

installnone
runtimebun
networkno
when to choose it
whenBuilding the docs site or a staging preview: an IG instance needs its artefact pages.
limitsNarrative pages are not held — the harvest keeps artefacts — so menu entries link upstream. Bodies are still partly HTML inside markdown.
costSeconds; one file per artefact.

What it is made of

It draws the viewer for the graph typology fhir-artifact-index.

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-pages.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-pages.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-pages",
  "title": "Generate an IG instance's reader-facing pages from its artefact index",
  "description": "Write `<instance>/docs/` — an index page, one page per artefact, a page per over-large category and per menu group — from `fhir-artifact-index/index.json` (and `menu.json` when ingested), styled by the template chrome an owning instance ingested. For an instance whose docs declare `igSite` it writes no index, menu or category pages — the IG site's own replace them — and only a front-matter `artifacts.md` naming the Tool that drew it. `build-ig-site` renders an IG's narrative pages from source; this Tool writes the artefact pages for every IG instance (`stage-ig-sites` copies them in).",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/gen-ig-pages.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "instance",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The instance directory: holds `fhir-artifact-index/` and receives `docs/`.",
        "required": true,
        "arg": {
          "flag": "--instance"
        }
      },
      {
        "name": "site",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Where an instance declares a visualiser `renderedBy: ig-pages`, the Tool writes that visualiser's route page. With this site directory it writes ONLY those route pages (`<locale>/<harness>/<id>/` and, per instance, `…/<instance>/`) under it: not `docs/`, not the instance. Each opens the IG's artefact index.",
        "required": false,
        "arg": {
          "flag": "--site"
        }
      },
      {
        "name": "label",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "The IG's display name. The index carries only the package id, which stands in when this is absent.",
        "required": false
      },
      {
        "name": "chrome-owner",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "The instance whose `chrome.json` styles the pages. Absent, the pages are unstyled and the build says so. The banner's identity is always the index's; a chrome ingested from another IG lends its tokens, never its status.",
        "required": false
      },
      {
        "name": "summary",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Open the index page with the instance's own declaration (`harness_details.html` with `instance=`), making it the instance's landing page.",
        "required": false
      },
      {
        "name": "full-pages",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Default: each artefact page is a thin shell at the same address, with its JSON-LD node, the index node (`artifact/index.jsonld`) and the shared renderer `assets/ig-artifact.js`. With it: full pages, no JSON-LD.",
        "required": false
      },
      {
        "name": "jsonld-base",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Url",
        "description": "Thin pages only: the docs root's published URL, so each node's IRIs are absolute. Absent, they are relative to the node's own file.",
        "required": false
      },
      {
        "name": "compiled-data",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Where a compiled index's resource files are served, as a path from the docs root. `.` means each is served once at the docs root as `<Type>-<id>.json`, as the IG site does; a docs root beside the AST passes `../ast-data`.",
        "required": false
      },
      {
        "name": "check",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Write nothing; exit 1 when any page is stale or orphaned.",
        "required": false
      }
    ],
    "outputs": [
      {
        "name": "pages",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "Pages written; the menu and chrome are reported as present or COULD NOT DETERMINE, never silently absent."
      }
    ]
  },
  "satisfies": [
    "ig-build-pipeline"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "renders": [
    "fhir-artifact-index"
  ],
  "selection": {
    "when": "Building the docs site or a staging preview: an IG instance needs its artefact pages.",
    "limits": "Narrative pages are not held — the harvest keeps artefacts — so menu entries link upstream. Bodies are still partly HTML inside markdown.",
    "cost": "Seconds; one file per artefact."
  }
}

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