Skip to content
Connected RailsConnected Rails

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.

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).

Node.js 22.12 or newer:

Terminal window
cd docs
npm ci
npm run dev # http://localhost:4321, reloads on every save
npm run build # the full site into docs/dist, with the link check

A local build is served from / and has no version picker.

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:

Terminal window
DOCS_VERSION=0.2 DOCS_VERSION_LABEL=0.2.1 DOCS_REF=$(git rev-parse HEAD) npm run build
node scripts/versions.mjs builds # what a deploy builds: slug, label, commit
node scripts/versions.mjs list # versions.json as it would be written

On 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.

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 main that touches docs/;
  • 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.

  1. 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.
  2. Build type Dockerfile, Dockerfile path Dockerfile, build path /.
  3. Under Domains: docs.connected-rails.org, container port 80, HTTPS with Let’s Encrypt.
  4. Create an API key (Settings → Profile → API/CLI) for a user who may deploy that application.
  5. 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.