Rune renders the website from Markdown in   docs/  . It exports static HTML, then starts the same view through WebAssembly and WebGPU where available. GitHub Pages serves the files without an application server.

Preview and verify

You need Node.js 22.23.4+, npm, Rust 1.99.1, its Wasm target, and wasm-bindgen CLI 0.2.129. These are website tools, not Plous runtime requirements.

Shell command

npm ci --prefix website rustup toolchain install 1.99.1 \ --profile minimal --target wasm32-unknown-unknown cargo +1.99.1 install wasm-bindgen-cli --version 0.2.129 --locked make website-check make website-build npm --prefix website run preview

Open   http://127.0.0.1:8046/plous/  . Rebuild after source edits. Stop the preview with Ctrl+C.

Check

What it verifies

  make docs-check

Source titles, links, anchors, navigation, prose punctuation

  make website-check

Content mapping, examples, headings, redirects, publication rules, Rune compilation

  make website-build

Full export, generated links, assets, search, syntax colors

Review Quickstart, MCP setup, and a long reference at desktop and mobile widths. Check search, copy, theme, and code colors. Use   ?static=1   for static HTML. The document's   data-runtime   reports the live Rune handoff.

Passing structural checks does not establish readability. Read each changed guide as a user following its steps.

Layout and browser integration

Source

Owns

  website/rune/src/lib.rs

Layout, typography, colors, icons, Markdown rendering

  scripts/navigation.mjs

Flat sidebar groups

  scripts/prepare.mjs

Markdown, links, headings, compiler input

  scripts/build.mjs

Native HTML export, Wasm, fonts, assets, search

  scripts/template.html

Metadata and browser dialogs

  scripts/client.mjs

Static controls, dialogs, themes, live startup

  scripts/publish.py

Release archives, corrections, version assembly

Paths in this table are under   website/  . Generated input, outputs, and dependencies are ignored by Git. The build includes Rune and Geist license files from the pinned dependency checkout.

Do not use   MarkdownStyle::shell_code   for syntax-colored examples. Rune treats that option as plain shell text. Use the normal code-block theme and syntax palette.

Keep one source under   docs/  . Relative guide links become website routes. For example,   docs/getting-started/README.md   becomes   /plous/docs/getting-started/   at the default alias.

Write one task per guide. Put exact commands and limits in references. Keep implementation details in contributor pages.

Use short sentences and concrete names. Avoid semicolons and em dashes in prose. Put warnings beside the action they affect. Code and quoted output keep their literal punctuation.

Label code fences by language. Format long argument arrays across lines. Keep plain-text output separate from commands. Verify colors in light and dark themes, static HTML, and live Rune.

Place the interactive examples where they help explain a step. The   plous-example   markers in Quickstart render the terminal recording and panel controls.

Keep the approved flat navigation groups and separate Argo CD and Flux guides. Preserve public routes and heading links when moving content. Development source links use main. Release corrections link to their exact source commit.

GitHub Pages setup

Enable Settings → Pages → Source → GitHub Actions. Allow the   github-pages   environment to deploy from main. Only the deployment job receives Pages write permissions.

The published site is simjay.github.io/plous.

Actions variable

Default

  PLOUS_SITE_URL

  https://simjay.github.io

  PLOUS_SITE_BASE

  /plous

For a custom domain, configure Pages and DNS, then set the origin and base. Check domain-root builds locally:

Shell command

PLOUS_SITE_URL=https://docs.example.com \ PLOUS_SITE_BASE=/ make website-build

Pages receives   website/published/  . Build outputs, private data, and local internals stay out of source control.

Publication and recovery

Event

Result

Pull request

Validate and build a downloadable preview. No deployment.

Main push

Update Development and preserve published versions

Application release

Save the tagged docs archive and queue Pages

Documentation correction

Add a commit-identified correction and republish that version

Default routes open the latest released version.   /plous/dev/   follows main.   /plous/v0.0.3/   serves docs for that application version. Search stays within the selected version.

Release archives and SHA-256 files live as GitHub release assets. They do not depend on expiring Actions artifacts. Each Pages build verifies and assembles all published versions.

Correct released docs

Run Correct released documentation from a revision whose application source matches the release. This command corrects v0.0.3 from a matching main revision.

Shell command

gh workflow run docs-correction.yml --ref main \ -f release_version=v0.0.3

The workflow rejects a draft release, a version mismatch, or application-source changes relative to the tag. It builds the current documentation and records its exact commit.

Corrections add new archives without replacing the original snapshot or application assets. Pages uses the newest complete correction. The application version and release tag do not change, and Homebrew is not triggered.

If main has advanced beyond the target release, start from that version's current documentation source and apply the relevant website and guide changes. Push a correction branch and pass it to   --ref  . Keep the release branch's application source and version-specific instructions intact.

Recover a failed publication

Rerun failed jobs or dispatch Documentation website on main. An invalid archive or failed build leaves the current site available.

A correction retry reuses existing assets for that commit and finishes a partial upload. It does not overwrite published archives. The next successful Pages build includes it.

Confirm the workflow result and public URL before reporting deployment success.

View source

On this page

Plous · Open source · Early development

Search Plous docs

Search the documentation.

Documentation versions