# Self-host this wiki

This builds the reference website, not an interactive ScoreScript editor.
For notation on an existing site, see [embedding](embedding.md).

## Build

Prerequisites: authorized repository access, Rust/Cargo, and Node with the
built-in test runner. From the repository root:

```sh
npm --prefix website run build
```

The build reads the authored Markdown in `docs/wiki/`, validates every
ScoreScript example with the native engine, and generates reference tables
from that engine. It also checks local links and the published artifact set.
A failed check stops the build; publish only a successful build's output.

Output goes to `website/dist/`. That directory contains HTML, CSS, JavaScript,
notation SVGs, example downloads, Markdown chapters, and machine-readable
reference files. No runtime database or Rust installation is needed on the
web server.

## Publish

Upload **only `website/dist/`** to a static host. Do not upload the repository,
private documents, build caches, or credentials. Use a dedicated domain or
subdomain: the current site has root-relative `/docs/`, `/examples/`, and asset
paths, so uploading unchanged beneath `/some/subdirectory/` is not supported.

The generated `_headers` and `_redirects` files are hosting metadata. Hosts
that do not understand them need equivalent configuration, including security
headers and the documented redirects. Check a chapter URL directly, not just
navigation from the home page.

The discovery index uses `https://scorescript.org` as its canonical origin.
For an independent mirror, change that origin in `website/scripts/build.mjs`
to your own domain before building. Do not use a global text replacement on
all documentation: external reference links may intentionally point elsewhere.

## Update from code

Edit the relevant `docs/wiki/*.md` file, run the same build, then publish the
new `dist/`. A native language change regenerates the tables and rechecks the
examples on the next build. It cannot automatically write a correct explanation
of a changed language rule; that prose must be reviewed alongside the code.

The CLI and MCP embed the authored Markdown at compilation time. Rebuild those
binaries to pick up chapter edits; deploying the website alone does not update
an already installed CLI or agent server.

A source-control deployment can run this build whenever relevant code or
Markdown changes. Keep publication behind the successful checks, and retain
the previous deployed artifact for rollback. A filesystem watcher by itself
is not a deployment pipeline.

Before making a public mirror, confirm permission to publish the selected
documentation and artifacts. Access to a private checkout is not a public
redistribution license.