Publishing with GitHub Pages

The intended address is dynamicalsystemsgroup.github.io/sysml-concept-reference. That address is a deployment target, not evidence that publication has completed. Check the repository's Pages workflow for the actual deployment result.

Build and preview locally

Use the appropriate development context before installing development tools or contacting GitHub. For this workspace:

source ~/.config/direnv/direnvrc
use_dsg
ctxcheck
git status --short
uv sync --locked
uv run --locked python scripts/build_profiles.py
uv run --locked python scripts/build_notation.py
uv run --locked python scripts/build_shapes.py
uv run --locked python scripts/check_inventory.py
uv run --locked python scripts/build_browser.py
uv run --locked python scripts/build_site.py
uv run --locked python -m http.server 8000 --bind 127.0.0.1 --directory _site

Open http://127.0.0.1:8000/. Stop the preview server with Ctrl-C. _site/ is generated and ignored by Git. The site builder checks internal links and fragments and uses relative URLs so the same site works beneath the GitHub Pages repository path.

The builder publishes an explicit set of inputs: the homepage, research Markdown, generated browser, selected inventory data, RDF files and queries. It does not publish sandbox/, environments, credentials or arbitrary repository files. Links to source scripts open those files in the GitHub repository. Raw OMG downloads remain ignored.

First publication

After the user explicitly authorizes committing and pushing:

1. Review the diff and stage explicit paths. Commit the inventory and Pages setup, then push main through the context-specific SSH remote.
2. In GitHub repository Settings → Pages, choose GitHub Actions as the build source. An administrator can also create the Pages site through the GitHub Pages REST API using build_type: workflow.
3. Run Deploy GitHub Pages from the Actions tab if the initial push happened before Pages was enabled.
4. Wait for the deployment to finish, then verify the public homepage, browser, documentation and downloadable data at the Pages URL.

The project declares its seven-day package release cutoff in pyproject.toml, so the lockfile does not depend on a contributor’s global uv configuration.

The workflow runs on pushes to main, pull requests to main, and manual dispatch. Pull requests build and validate only; deployment is restricted to main outside pull requests. The build job has read-only repository access. The deploy job has Pages deployment and identity-token permissions and uses the github-pages environment. Action references are pinned to reviewed commit SHAs.

Updating the site

Edit research notes in docs/, the homepage in site/index.md, and the documentation style in site/style.css. The shared page frame and evidence panels are generated by scripts/page_layout.py. Reading aids live in site/site.js; the concept workspace adds site/browser.css. The browser and gallery embed these shared styles and reading aids for portable use, so regenerate both after changing them. Browser content and interactions live in scripts/browser-template.html; gallery interactions and layout live in scripts/shapes-gallery.js and scripts/shapes-gallery.css. For data changes, follow the RDF reproduction guide, including pinned-source checks where applicable.

Run:

uv run --locked python scripts/build_profiles.py
uv run --locked python scripts/build_notation.py
uv run --locked python scripts/build_shapes.py
uv run --locked python scripts/check_inventory.py
uv run --locked python scripts/build_browser.py
uv run --locked python -m unittest discover -s tests -v
uv run --locked python scripts/build_site.py

Commit and push only when explicitly authorized. A successful deployment publishes the new site automatically. CI uses checked-in RDF and does not fetch OMG originals on each deployment; source-dependent tests report skips when the ignored originals are unavailable. Run the source audit locally with the pinned downloads before publishing source-derived changes.

Hosting choice

GitHub Pages supports the existing interactive HTML browser and publishes the notes and data from a single Git history. A GitHub wiki would add a second repository and would not serve that browser as a website. This setup follows GitHub's custom Pages workflow documentation.

DSG identity

Shared colors and locally hosted fonts live in site/brand.css; layout rules live in site/style.css. Official logo assets, original URLs, hashes and font licenses are recorded in site/assets/provenance.json. The browser receives the same assets for offline use. Preserve formal notation geometry when applying presentation colors.

Browser verification

After building and starting the preview server, use the Playwright CLI to run tests/site-browser-check.js and tests/shapes-browser-check.js. With an existing CLI session named dsg, run from ignored sandbox/ so captures stay out of Git:

playwright-cli -s=dsg run-code --filename=../tests/site-browser-check.js
playwright-cli -s=dsg run-code --filename=../tests/shapes-browser-check.js

The site check covers all twenty-nine shared-frame routes at 1440, 390 and 320px, concept/property navigation, stable fragments, gallery inspection and module failure, keyboard entry, static reading, print disclosures and reduced motion. It retains screenshots and a print PDF for visual review. The shape check covers filters, copy failures, the renderer example, safe labels, clone identities and static downloads. These optional browser checks require a local Playwright CLI/browser installation; the Python test suite does not install a browser or run them.

The bounded parts-and-ports milestone has an additional tests/parts-ports-browser-check.js check, run with the same CLI command pattern. It exercises the reference, audit, coverage and register at three widths; all twenty component previews; literal row editing and copy; row-control reset; the published 50-unit ledger; and static reference/download access. Rebuild profiles, notation, shapes and browser before running it.