In CI
check is the gate: it exits 1 when any example fails to validate or render. build is the preview: upload the site and every PR gets a Studio a reviewer can download.
The Isomer repository has a composite action that runs both and uploads what they write. It runs the isomer-studio binary installed in working-directory, so install the pack's dependencies, @elastic/isomer-studio among them, first. Then:
- uses: elastic/isomer/.github/actions/isomer-studio@main
with:
config: isomer-studio.config.ts
| Input | Default | What it does |
|---|---|---|
config |
Required | The config, relative to working-directory. |
working-directory |
. |
Where the isomer-studio command resolves. config, out and report resolve against it. |
check |
true |
Runs check, writing a JUnit report. A failure fails the step. |
png |
false |
Adds --png to the check. |
report |
isomer-studio-report.xml |
Where the report goes. It uploads as <artifact-name>-report, even when the check fails. |
build |
true |
Runs build, even when the check failed. |
out |
dist/studio |
Where the site goes. |
base |
./ |
The URL path the site is served from. |
artifact-name |
isomer-studio |
The name of the uploaded site. |
The Isomer repository's Studio preview job builds the root isomer-studio.config.ts from the PR's head commit, not the merge ref, and uploads it as studio-<headSha>-<runId>-<attempt>. Unzip it into a directory named studio, serve that directory's parent with npx serve ., and open /studio/.
The action is two commands. On another CI system, run them yourself:
npx isomer-studio check --config isomer-studio.config.ts --format junit --report isomer-studio-report.xml
npx isomer-studio build --config isomer-studio.config.ts --out dist/studio
npx @elastic/isomer-studio check also works without installing the Studio, but an installed one keeps CI on the version the lockfile pins.
build and check --png rasterize with @elastic/isomer-image-takumi, a native dependency the Studio installs for the platform it runs on. A config with images: false never loads it.
To serve the Studio from a docs site, build it into the site's output with the path it will be served from:
npx isomer-studio build --config isomer-studio.config.ts --out site/studio-app --base /my-docs/studio-app/
Give the app its own directory, not the one the Studio's or the pack's docs build into, so neither overwrites the other.