Build pipeline

docusystem build and docusystem check run one pipeline. Steps 1 to 14 are build; steps 15 to 17 are added by check. Every step prints with its stage prefix, and problems are collected rather than thrown until step 10.

Why a generated project root

Jx 5.0.0 has no project-level composition. It reads pages/, components/*.json (flat), public/ and the layout chain only from the project root, a nested layout is resolved against that root, components cannot be registered from a package, and project.json has no extends. So the package assembles a plain Jx project root from real file copies and runs the released Jx compiler on it with jx build <root>. That uses only documented Jx surfaces: no Jx extension, no hook, no mutation of Jx internals.

Jx also ignores what it does not understand and still exits 0: an unknown key, an unregistered component (an empty custom element is emitted). The pipeline therefore asserts the output positively (step 12).

The steps

A failed strict build leaves the previous <site>/dist untouched.

Jx evaluates every string that holds ${ as JavaScript, and its parser makes inert only the text of a page, not an address, a URL, a raw HTML attribute, a directive or the language of a fence. Step 5 therefore writes every ${ of a page with a zero-width space between $ and {, in code and front matter as well and in every spelling that Markdown, HTML or YAML decodes to it, and step 7 does the same for the sidebar data. Step 11 writes the marker back as ${ in every text node, so prose and code read as written; an attribute value keeps it. See the trust model.

The assertions of step 12

• Every component file of the root was emitted as components/<name>.js.

• No registered custom element is left empty (not rendered).

• No page has an empty link: an <a href> with no text, image or aria-label. A raw HTML anchor in the Markdown is the usual cause, and step 6 reports it as a lint error with its file and line.

• Exactly one <h1> per page.

• The <title> of every page is text: the head has one <title> and one </title>. Jx writes the title text as it is, so a title that holds </title> would end the element and leave what follows it as live HTML in the head.

• No unevaluated template text in the output: a dollar sign, an opening brace and the word state, which would mean a page template was not evaluated.

• CNAME equals domain.

• At least one fonts/*.woff2; @font-face URLs are local; no third-party font host appears.

• favicon.svg, favicon.ico and .nojekyll exist.

• search-index.json has an entry for every docs page.

• sitemap.xml is present and on the configured domain.

• 404.html is present and there is no /404/ folder.

• There are no *.md copies.

• The project switcher is pre-rendered from the catalog.

• The route count of step 10.

• No page holds a script, an event handler, a javascript:, data: or other unsafe address, or an embedded page (iframe, object, embed, form, base), and the page content (docs-prose) holds no script, style, link or meta and no style attribute. This reads what Jx wrote, so it also catches what raw HTML, links, images and :name{...} directives made.

• Every file Jx published from the Markdown folder (content/) is not active: no .html, .js, .xsl or similar, no SVG with scripts or handlers, no XML that says it is XHTML or SVG.

• Every page with a head carries a Content-Security-Policy meta before its first script, whose script-src is open to nothing but the site and names each inline script by its hash.

The Content-Security-Policy

Documentation is other people's text on a domain that is same-site with the client portal, so the pages say what they may do. Step 11 puts this meta first in the head of every page (after <meta charset>), with the hashes of the page's inline scripts filled in:

default-src 'self'; script-src 'self' 'sha256-...'; style-src 'self' 'unsafe-inline'; img-src 'self' https:;
font-src 'self'; connect-src 'self' https://avunu.net; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'

A browser then refuses an inline event handler, a javascript: address, an inline script the build did not write and any script from another origin; it embeds nothing, cannot be sent to another <base> and submits no form. Styles keep 'unsafe-inline' because the pages carry <style> blocks. Images may come from any https site, so that a page can show the badge of its repository. avunu.net is the project switcher's live catalog. A policy that a project's own layout adds is enforced too, and can only narrow this one. A jx fragment that adds a script from another origin to $head is blocked by it: that is the cost of the unsupported rung, and the reason to ask for the change in the package instead. docusystem dev serves the same pages, so its reload script is a file (/__reload.js) and not an inline script.

The generated project root

<site>/.docusystem/                git-ignored; contains its own .gitignore with the single line *
  lock                             pid file
  manifest.json                    written by assemble
  jx.log                           raw stdout and stderr of the last Jx run
  serve/                           dev only: the copy of dist the dev server answers from
  site/                            THE JX PROJECT ROOT (recreated empty on every run)
    project.json                   generated from the package's project.base.json
    docusystem.config.json         the resolved config
    components/ layouts/ pages/    package copies, then overrides on top
    public/                        package public/, then <site>/public/, then CNAME
    data/projects.snapshot.json    the bundled catalog
    .generated/docs/               the staged Markdown
    .generated/nav.json            sidebar, previous and next, landing cards
    node_modules/@jxsuite/         links to the installed compiler, parser, runtime and search
    dist/                          the Jx build output, post-processed in place
<site>/dist/                       the published copy; the only path CI uploads

The layouts and pages read the resolved config through the content type config, the sidebar through nav and the project switcher through projects; the docs content type reads ./.generated/docs.

The manifest

.docusystem/manifest.json records what the build did:

{
  "docusystem": "0.1.0",
  "runtime": "node 24.21.0",
  "jx": {
    "@jxsuite/compiler": "5.0.0",
    "@jxsuite/parser": "2.0.0",
    "@jxsuite/runtime": "4.0.3",
    "@jxsuite/search": "0.4.0"
  },
  "files": {
    "components/docs-footer.json": "override",
    "pages/index.json": "package",
    "project.json": "generated",
    "public/CNAME": "generated"
  },
  "shadowed": ["components/docs-footer.json"],
  "added": ["pages/about.json"],
  "catalog": "bundled",
  "strict": true
}

files lists every file of the root except node_modules/, dist/ and .generated/docs/, sorted by path, with its origin: package, override or generated. catalog is bundled, or live with --refresh-catalog. The versions in the example are an illustration of the shape; the file records the ones installed.

The catalog

The project switcher is built from a catalog bundled in the package, so the build needs no network and the output does not depend on avunu.net at build time. A weekly job in this repository proposes a refresh as a patch release. In the browser the page swaps in the live https://avunu.net/projects.json when idle; while avunu.net does not serve it, the fetch fails quietly and the bundled list stays (an entry without a docs address then links to its page on avunu.net, which exists only once avunu.net has relaunched: see the order of launch). --refresh-catalog makes a build fetch the live one (a 5-second timeout) and accept it only if it passes the version-1 contract; otherwise the build keeps the bundled one and prints a catalog: warning. The contract bounds the text as well as the shape: a slug is a config slug, and no string in the document may hold ${, <, > or a control character, because the compiler evaluates a ${...} in what a page renders and a catalog that held one would run code in every site's build.

The dev server

docusystem dev runs steps 1 to 14 leniently once. Then it serves <site>/.docusystem/serve, an atomically swapped copy of <site>/dist, on 127.0.0.1:<port> with GitHub Pages semantics:

• A directory without a trailing slash answers 301.

• A missing path answers 404 with 404.html.

• Path traversal is refused.

• An event stream at /__reload and a reload script injected before </body> of HTML pages reload the browser.

It watches the docs folder, overrides/, public/ and the config file. Changes are debounced by 150 ms and rebuilds are serialized: one more only if a change arrived during a build. The lock is held only during a build. A failed rebuild keeps serving the last good copy and prints the problems, and the browser reloads only after a successful build. It binds only to loopback.

What CI runs

Pull request (docs.yml calling docs-build.yml, token contents: read): check out without credentials; require package-lock.json and refuse bun.lock; Node 24 without a package cache; npm ci --ignore-scripts; npm audit signatures and the provenance assertion; CI=true ./node_modules/.bin/docusystem check --ci; upload <site>/dist as the 7-day artifact docs-site for review; on failure upload the debug artifact.

Push to the default branch or a manual run (docs-publish.yml): the same build job, with the Pages artifact when DOCS_SITE_ENABLED is true, then, only when it is, docs-deploy.yml. See Workflows.