This documentation
The documentation is a Starlight site in
docs/, published at
docs.connected-rails.org. Every page is a Markdown file
under docs/src/content/docs/; the directory it sits in is the sidebar group it shows up in:
| Directory | Sidebar group |
|---|---|
play/ |
Playing |
modding/ |
Modding — the overview page |
modding/guides/ |
Modding → Guides |
modding/tools/ |
Modding → Editors and tools |
modding/reference/ |
Modding → Reference |
develop/ |
Developing |
A guide walks through one task step by step and links into the reference for the full field lists; a reference page lists every field of one kind of file and stays complete. New file formats go into the reference, new workflows into a guide.
Writing a page
Section titled “Writing a page”A page starts with its front matter instead of a # heading — the title is rendered from
it — and a one-line description, which search engines and link previews show:
---title: "Shunting"description: "Coupling, uncoupling, stabling roads and portals, AI shunt jobs."sidebar: order: 5---
Text, starting with `##` sections.sidebar.order sorts the pages of a group. Links are relative paths to files, exactly
as they would be written for the forge’s file browser, so a page reads the same there, in an
editor and on the site:
- to another page:
[controls](../play/controls.md#gamepad)— the build turns it into the page’s address in the same version of the docs; - to code or anything else in the repository:
[theme.rs](../../../../../crates/app/src/theme.rs)— the build turns it into a link to that file on the forge, at the commit the docs were built from, so the docs of a release link the code of that release.
A link to a page or an anchor that does not exist, or to a file that is not in the
repository, fails the build (starlight-links-validator
and src/plugins/repo-links.mjs).
Change the documentation in the same pull request as the code it describes (see CONTRIBUTING.md).
Building it locally
Section titled “Building it locally”Node.js 22.12 or newer:
cd docsnpm cinpm run dev # http://localhost:4321, reloads on every savenpm run build # the full site into docs/dist, with the link checkA local build is served from / and has no version picker.
Versions
Section titled “Versions”Every version of the docs is a complete build of the site under a path of its own:
| Path | Built from | When |
|---|---|---|
/nightly/ |
the tip of main |
every deploy |
/0.2/ |
the newest v0.2.* tag (v0.2.0-rc.1, v0.2.0, v0.2.1, …) |
every deploy |
/ |
redirect to the default version | every deploy |
Every deploy builds all of them again from git, so one release line has one set of docs
and a hotfix release replaces them: after v0.2.1, /0.2/ is built from v0.2.1, while
v0.3.0 adds /0.3/ and builds /0.2/ from the same tag as before.
The default version — where / and a link without a version (/play/controls/) lead —
is the newest line whose newest release is stable, or the newest line at all while every
release is a prerelease, or nightly while there is none.
The site’s root holds three files besides the version directories, all written by
scripts/versions.mjs from the git tags alone:
versions.json (the list the version picker reads when a page loads, so the docs of 0.1
offer 0.3 without being rebuilt), index.html (the redirect) and 404.html (sends a path
without a version on to the default one). A tag has docs of this kind if its tree contains
docs/astro.config.mjs; older tags are left out.
Which version a build is comes from the environment, which
src/build-info.mjs reads:
DOCS_VERSION=0.2 DOCS_VERSION_LABEL=0.2.1 DOCS_REF=$(git rev-parse HEAD) npm run buildnode scripts/versions.mjs builds # what a deploy builds: slug, label, commitnode scripts/versions.mjs list # versions.json as it would be writtenOn every page but the default version’s, a banner says which version the reader is in — the development version, a preview of the next release, or an older one — and links the same page in the default version.
Deployment
Section titled “Deployment”The docs workflow builds the site on every pull
request that touches docs/ (the link check is part of the build) and deploys it to
Dokploy:
- on a push to
mainthat touchesdocs/; - on every
v*tag; - by hand (Actions → Docs → Run workflow) — for instance after the server was set up again.
A deploy does not add to what is on the server, it replaces it: the workflow builds every
version of the table above from its own commit (versions.mjs builds, one git worktree
each), writes the three root files beside them, and zips the result together with
deploy/Dockerfile and
deploy/nginx.conf. It uploads the zip as a drop
deployment (application.dropDeployment of Dokploy’s API); Dokploy unpacks it, builds the
image — nginx with the site in it — and swaps the container. The run ends once Dokploy
has queued the deployment, so a failed image build shows up in Dokploy’s deployment log,
not in the workflow. Deploys run one at a time.
The nginx configuration answers a missing path with /404.html, has every page, the
versions.json and the redirect revalidated (Cache-Control: no-cache) and caches only
the hashed files under _astro/ for good. TLS is Dokploy’s Traefik.
Setting up Dokploy
Section titled “Setting up Dokploy”- Create an application (Projects → a project → Create Service → Application). Its source is set to Drop by the first deploy; until then any source will do.
- Build type Dockerfile, Dockerfile path
Dockerfile, build path/. - Under Domains:
docs.connected-rails.org, container port 80, HTTPS with Let’s Encrypt. - Create an API key (Settings → Profile → API/CLI) for a user who may deploy that application.
- Put three secrets into the repository’s settings (Settings → Actions → Secrets):
| Secret | Holds |
|---|---|
DOKPLOY_URL |
the address of the Dokploy panel, https://dokploy.example.org |
DOKPLOY_API_KEY |
the API key of step 4 |
DOKPLOY_DOCS_APPLICATION_ID |
the application’s id, the last part of its address in the panel |
Without them a pull request still builds; a deploy stops with an error. Then start the workflow by hand once.
To try the image locally after a build: put dist/ into deploy/site/nightly/, run
node scripts/versions.mjs root deploy/site, then docker build -t docs deploy and
docker run --rm -p 8080:80 docs. deploy/site/ is ignored by git.