@guestcraft/docs

The documentation website, published at https://spinny03.github.io/guestcraft/. It is an Astro Starlight site that reads the repository’s Markdown where it lives: there is no copy of any document here.

What it publishes

• Every Markdown file under docs/, except the technical-analysis sources, the product presentation, the review rounds of docs/architecture/reviews and the ADR template.
• The community files at the root: CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, SUPPORT.md, TRADEMARK.md, CODE_OF_CONDUCT.md and AGENTS.md.
• The README of every package in apps/, packages/ and tooling/.
• The landing page, in English and Italian (src/content/docs), the only pages written for the site.
• The API reference: the checked-in openapi/v1.json, rendered by Scalar’s standalone bundle, which the site serves itself.
• docs/developer/deploy-secrets.html, byte for byte, at /guestcraft/developer/deploy-secrets.html, the path the Deploy Buttons link to.

A page’s URL mirrors its file: docs/developer/api.md is /guestcraft/developer/api/, packages/sdk/README.md is /guestcraft/packages/sdk/. The page title is the document’s first heading, so documents keep no front matter. A relative link to a published document becomes a link to its page; a link to anything else, such as source code, goes to the file on GitHub.

Writing documents for the site

• Start the document with its SPDX notice and one level-one heading, as today.
• Link to other documents with relative paths to the .md files, as on GitHub.
• A new document appears on the site and in the sidebar by itself. The sidebar groups pages by audience in src/sidebar.ts; a page that no group names is listed under “More” until it is placed.
• Images and other files linked from a document are linked on GitHub.

Commands

pnpm --filter @guestcraft/docs dev        # http://localhost:4300/guestcraft/
pnpm --filter @guestcraft/docs build      # dist/, then the link check
pnpm --filter @guestcraft/docs preview    # the build at http://localhost:4301/guestcraft/

build fails if any link of the built site, in any page, does not resolve to a page, a file or an element of the build (src/check-links.ts). The check is offline: links to other sites are not fetched.

Privacy and cost

Search is Pagefind’s local index, built with the site. The site loads no analytics, no remote fonts (Inter is served by the site) and no third-party scripts. The API reference page turns off Scalar’s telemetry, hosted fonts, request client and hosted services, and its Content Security Policy allows requests only to the site itself.

Publishing

.github/workflows/docs.yml builds the site on every pull request and deploys main to GitHub Pages with the official Pages actions. Pages must use GitHub Actions as its source (Settings → Pages → Build and deployment → Source).