Stage one IG as its own just-the-docs Jekyll site

Turn an IG source repository into ONE Jekyll source for just-the-docs, as the IG Publisher builds one IG per site: input/pagecontent pages with title, parent and order from sushi-config.yaml pages:, the files the Publisher’s include tags resolve against, images, _data/fhir.json from ig-site-data, and a _config.yml. The pages render unchanged, including their references to the IG’s site data. With the IG’s menu, the layout is the one every IG site wears: the IG’s own top bar, the IG’s TOC declared as the folio-assistant navbar’s section (added by rail-standalone-pages), no sidebar of its own, an edit link per page, and per heading a source-line link and a pre-filled feedback issue.

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: fhir-core, ig-artifact-jsonld, ig-ast-refresh, ig-index-build, ig-page-render-qa, 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.

porttyperequireddescriptionconstraint
inig-srcRepoPathyesThe IG source repository: sushi-config.yaml and input/.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inoutRepoPathyesThe Jekyll source directory to write.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inbaseurlRepoPathWhere the built site is served.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inplantuml-jarRepoPathRender input/images-source/*.plantuml as the Publisher does; without it a visible not rendered marker stands in.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
indedupe-idsRepoPathThe post-build pass, run INSTEAD of staging: over one IG’s BUILT pages (<site>/<instance>, after the host’s Jekyll build), keep the first copy of each anchor the IG’s source repeats, where every link already lands, rename the rest, and report each one. A host composing IGs runs it once per line of stage-ig-sites’ build list (process ig-docs-site-compose).string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outpagesCountPages staged.integer · A non-negative count — how many of something, or how many to show. Zero is a real answer.
outnot-renderedCountIncluded files the source does not hold and nothing rendered, each replaced by a VISIBLE marker and listed, never an empty include.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/build-ig-site.ts.
  • GitHub Actions. 2 workflow line(s) run its command:
workflowline
.github/workflows/docs-site.yml613bun run fhir-harness/scripts/build-ig-site.ts --dedupe-ids "./_site/${INSTANCE}"
.github/workflows/feature-staging.yml1185bun run fhir-harness/scripts/build-ig-site.ts --dedupe-ids "./_site/${INSTANCE}"

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

installnone
runtimebun
networkno
when to choose it
whenRendering an IG’s own pages through just-the-docs.
limitsFragments only the Publisher’s own generation writes (dependency tables, artefact summaries) are not produced here and show as markers. A page sushi-config.yaml does not list keeps its file name as title and is reported.
costSeconds; copies files. Rendering diagrams adds a Java process per diagram.

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/fhir-harness/tools/build-ig-site.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/build-ig-site.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
  "name": "build-ig-site",
  "title": "Stage one IG as its own just-the-docs Jekyll site",
  "description": "Turn an IG source repository into ONE Jekyll source for just-the-docs, as the IG Publisher builds one IG per site: `input/pagecontent` pages with title, parent and order from `sushi-config.yaml` `pages:`, the files the Publisher's include tags resolve against, images, `_data/fhir.json` from `ig-site-data`, and a `_config.yml`. The pages render unchanged, including their references to the IG's site data. With the IG's menu, the layout is the one every IG site wears: the IG's own top bar, the IG's TOC declared as the folio-assistant navbar's section (added by `rail-standalone-pages`), no sidebar of its own, an edit link per page, and per heading a source-line link and a pre-filled feedback issue.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/build-ig-site.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "ig-src",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The IG source repository: `sushi-config.yaml` and `input/`.",
        "required": true
      },
      {
        "name": "out",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The Jekyll source directory to write.",
        "required": true
      },
      {
        "name": "baseurl",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Where the built site is served.",
        "required": false
      },
      {
        "name": "plantuml-jar",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Render `input/images-source/*.plantuml` as the Publisher does; without it a visible `not rendered` marker stands in.",
        "required": false
      },
      {
        "name": "dedupe-ids",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The post-build pass, run INSTEAD of staging: over one IG's BUILT pages (`<site>/<instance>`, after the host's Jekyll build), keep the first copy of each anchor the IG's source repeats, where every link already lands, rename the rest, and report each one. A host composing IGs runs it once per line of `stage-ig-sites`' build list (process `ig-docs-site-compose`).",
        "required": false
      }
    ],
    "outputs": [
      {
        "name": "pages",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "Pages staged."
      },
      {
        "name": "not-rendered",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "Included files the source does not hold and nothing rendered, each replaced by a VISIBLE marker and listed, never an empty include."
      }
    ]
  },
  "satisfies": [
    "ig-build-pipeline"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "Rendering an IG's own pages through just-the-docs.",
    "limits": "Fragments only the Publisher's own generation writes (dependency tables, artefact summaries) are not produced here and show as markers. A page `sushi-config.yaml` does not list keeps its file name as title and is reported.",
    "cost": "Seconds; copies files. Rendering diagrams adds a Java process per diagram."
  }
}

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