{
  "id": "publishing",
  "title": "Preview and static publishing",
  "description": "Validate locally, build dist, and host the result on any static platform.",
  "type": "guide",
  "status": "observed",
  "visibility": "public",
  "tags": [
    "workflow",
    "publishing",
    "github-pages"
  ],
  "related": [
    "home",
    "getting-started",
    "agent-interface"
  ],
  "sourceRefs": [
    "../../core/dev.mjs",
    "../../core/build.mjs"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Work with a local preview\n\nThe development server watches `content/`, `diagrams/`, `assets/`, and `site.config.json`, rebuilds the site, and asks the browser to reload.\n\n```bash\nnpx --no-install aurelius dev --site docs --port 4173\n```\n\nDocument routes work both with and without a trailing slash—for example, `/getting-started` and `/getting-started/` both serve the generated `getting-started/index.html`.\n\n## Validate before building\n\n`check` does not write `dist/`. It stops on duplicate IDs, broken relationships, missing anchors or assets, inconsistent diagrams, and unsafe output paths.\n\n```bash\nnpx --no-install aurelius check --site docs\nnpx --no-install aurelius build --site docs\n```\n\n## Publish on GitHub Pages with GitHub Actions\n\nIn the repository that owns the site, open **Settings → Pages** and select **GitHub Actions** as the publication source. Create `.github/workflows/deploy-aurelius.yml` with this workflow; adjust `main` and `docs` if your branch or site directory is different:\n\n```yaml\nname: Deploy Aurelius to GitHub Pages\n\non:\n  push:\n    branches: [main]\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\nconcurrency:\n  group: pages\n  cancel-in-progress: false\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - uses: actions/setup-node@v7\n        with:\n          node-version: 22\n          cache: npm\n      - run: npm ci\n      - run: npm run aurelius -- check --site docs\n      - run: npm run aurelius -- build --site docs\n      - uses: actions/configure-pages@v5\n      - uses: actions/upload-pages-artifact@v4\n        with:\n          path: docs/dist\n\n  deploy:\n    needs: build\n    runs-on: ubuntu-latest\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n    steps:\n      - id: deployment\n        uses: actions/deploy-pages@v4\n```\n\nCommit the site sources, the workflow, `package.json`, and `package-lock.json`; do not commit `docs/dist`. `build` recreates only the configured `outputDirectory`, and the workflow publishes the generated artifact. Relative links let the site work under a GitHub Pages project path or a custom domain without a base-URL setting.\n\nYou can host on another static platform too. Keep `content/`, `diagrams/`, `assets/`, and `site.config.json` in the repository; never hand-edit generated files.\n\nPublishing is all-or-nothing for the selected site root. `visibility` travels with each document as metadata but does not filter files or enforce authorization. If some material is private, protect the whole deployment at the host or maintain separate public and internal site inputs; never rely on `visibility: internal` to keep content out of `dist`.\n\n## Remove a site you no longer want\n\nThe documentation directory is independent from Aurelius itself. If you decide not to keep a `docs/` site, remove it from version control with `git rm -r docs` and remove or update the workflow so it no longer builds that path. That also stops the GitHub Pages deployment for the site.\n\n## Review PDF output\n\nThe print stylesheet forces the light palette, hides interactive navigation, and keeps ordinary code figures together on one page with `break-inside: avoid-page`. Authored HTML can use an explicit `svgSource` or one self-contained inline SVG marked with `data-aurelius-print-source=\"true\"`, so the PDF does not depend on printing an iframe. Keep the fallback's styles inside the SVG itself; styles from the HTML `<head>` cannot travel with a copied or printed vector. A code sample taller than the printable sheet is the browser's unavoidable exception; split unusually long examples into meaningful blocks before publishing.",
  "sections": [
    {
      "id": "work-with-a-local-preview",
      "level": 2,
      "title": "Work with a local preview",
      "text": "The development server watches `content/`, `diagrams/`, `assets/`, and `site.config.json`, rebuilds the site, and asks the browser to reload.   Document routes work both with and without a trailing slash—for example, `/getting-started` and `/getting-started/` both serve the generated `getting-started/index.html`.",
      "line": 1
    },
    {
      "id": "validate-before-building",
      "level": 2,
      "title": "Validate before building",
      "text": "`check` does not write `dist/`. It stops on duplicate IDs, broken relationships, missing anchors or assets, inconsistent diagrams, and unsafe output paths.",
      "line": 11
    },
    {
      "id": "publish-on-github-pages-with-github-actions",
      "level": 2,
      "title": "Publish on GitHub Pages with GitHub Actions",
      "text": "In the repository that owns the site, open **Settings → Pages** and select **GitHub Actions** as the publication source. Create `.github/workflows/deploy-aurelius.yml` with this workflow; adjust `main` and `docs` if your branch or site directory is different:   Commit the site sources, the workflow, `package.json`, and `package-lock.json`; do not commit `docs/dist`. `build` recreates only the configured `outputDirectory`, and the workflow publishes the generated artifact. Relative links let the site work under a GitHub Pages project path or a custom domain without a base-URL setting.  You can host on another static platform too. Keep `content/`, `diagrams/`, `assets/`, and `site.config.json` in the repository; never hand-edit generated files.  Publishing is all-or-nothing for the selected site root. `visibility` travels with each document as metadata but does not filter files or enforce authorization. If some material is private, protect the whole deployment at the host or maintain separate public and internal site inputs; never rely on `visibility: internal` to keep content out of `dist`.",
      "line": 20
    },
    {
      "id": "remove-a-site-you-no-longer-want",
      "level": 2,
      "title": "Remove a site you no longer want",
      "text": "The documentation directory is independent from Aurelius itself. If you decide not to keep a `docs/` site, remove it from version control with `git rm -r docs` and remove or update the workflow so it no longer builds that path. That also stops the GitHub Pages deployment for the site.",
      "line": 75
    },
    {
      "id": "review-pdf-output",
      "level": 2,
      "title": "Review PDF output",
      "text": "The print stylesheet forces the light palette, hides interactive navigation, and keeps ordinary code figures together on one page with `break-inside: avoid-page`. Authored HTML can use an explicit `svgSource` or one self-contained inline SVG marked with `data-aurelius-print-source=\"true\"`, so the PDF does not depend on printing an iframe. Keep the fallback's styles inside the SVG itself; styles from the HTML `<head>` cannot travel with a copied or printed vector. A code sample taller than the printable sheet is the browser's unavoidable exception; split unusually long examples into meaningful blocks before publishing.",
      "line": 79
    }
  ],
  "sourcePath": "content/publishing.md",
  "visuals": [],
  "apiVersion": 1
}