Router

This page is for site authors using qip route and qip dev.

It explains:

• where files should go
• what each command does
• what runs when (content recipes vs WARC recipes)

Project Layout

Typical setup:

site/                         # content root
  index.md
  how-it-works.md

docs/                         # optional additional content root
  index.md
  module-contract.md

recipes/                      # optional recipe root
  text/markdown/10-...wasm
  text/markdown/80-...wasm
  application/warc/10-...wasm

modules/                      # optional browser/module asset root
  utf8/trim.wasm
  application/warc/warc-check-broken-links.wasm

modules/form/                 # optional form module root
  contact.wasm

Related references:

• Content Layout v0
• Recipe Layout v0

Route Behavior

Given a content file like site/docs/module-contract.md, qip routes:

• pretty URL: /docs/module-contract
• source URL: /docs/module-contract.md

Common behavior:

• pretty URLs are where markdown recipes usually run (for HTML output)
• source URLs intentionally remain raw source (for example raw markdown)

What Runs When

qip dev <content_dir> ...

Per request:

1. Resolve request path to a content file or module asset.
2. For content pages, run matching content recipes (for example recipes/text/markdown/*).
3. If response is HTML, inject runtime support for <qip-form> and <qip-preview>.
4. If recipes/application/warc/* exists, apply that WARC recipe layer to this page response too.
5. Serve the final response.

Result: preview in dev matches route-archive behavior for WARC-level transforms.

qip route get <content_dir> <path> ...

Runs the same page pipeline as dev for one path and prints the response body.

qip route head <content_dir> <path> ...

Runs the same route pipeline but returns headers only.

qip route list <content_dir> ...

Lists all routed paths and content types.

qip route warc <content_dir> ...

1. Enumerate all routed paths.
2. Resolve each path to a response.
3. Build one WARC archive from those responses.
4. If recipes/application/warc/* exists, run it over the archive.
5. Emit final WARC bytes.

If --view-source is used, source artifacts are added as extra WARC records.

Recipe Layers

There are two independent recipe layers:

• content layer: recipes/<mime-type>/...
• examples: recipes/text/markdown/*, recipes/text/html/*
• runs when rendering each page

• archive layer: recipes/application/warc/...
• runs on WARC output
• also applied in dev per page so behavior stays consistent

Practical Build Pattern

Static export usually looks like:

1. qip route warc ./site --recipes recipes --forms modules/form --modules modules
2. pipe WARC into archive-processing modules (for checks or export)

Example pipeline:

qip route warc ./site --recipes recipes --forms modules/form --modules modules \
  | qip run modules/application/warc/warc-check-broken-links.wasm \
           modules/application/warc/warc-to-static-tar-no-trailing-slash.wasm

In this model:

• page transforms belong in recipes/text/...
• site-wide WARC transforms belong in recipes/application/warc/...