This documentation
This site is an Astro Starlight project in the
docs/ directory of
the slopcop repository, so it lives next to the code it describes and changes
in the same pull requests. Every page has an Edit page link.
Edit a page
Section titled “Edit a page”Pages are Markdown (or MDX, for pages that use Starlight components) under
docs/src/content/docs/, grouped by section. Each page starts with
frontmatter:
---title: Run a checkdescription: One sentence for search results and link previews.sidebar: order: 1---The sidebar is declared in docs/astro.config.mjs; add a new page there so it
appears. Link between pages with root-relative paths and a trailing slash
(/checks/exit-codes/); the build rewrites them for the deployment base and
fails on a link to a page that does not exist.
Write in the repository’s voice: plain sentences, the exact command or code name, and no claim the CLI or service does not make. The README and the agent skill are the source of truth for CLI behavior; keep them and this site in step.
Preview locally
Section titled “Preview locally”cd docsnpm cinpm run dev # http://localhost:4321npm run build # renders to docs/dist and checks every internal linknpm run check # astro checkNode 22 or newer. PUBLIC_DOCS_BASE=/slopcop npm run build proves the links
also hold when the site is served below a path prefix.
The social card is rendered from src/assets/social-card.svg into
public/og.png by npm run social-card; rerun it after changing the card.
Deploy
Section titled “Deploy”The Docs workflow (.github/workflows/docs.yml) builds the site and
deploys it to GitHub Pages, which serves it at
docs.slopcop.com. It deploys only from the
docs-production branch, so a page goes live with the release it describes, not
when its pull request merges.
docs-production stays an ancestor of master and only ever fast-forwards. Two
releases move it:
- a stable CLI release: the Release workflow fast-forwards
docs-productionto the tagged commit and runs the Docs workflow there (prerelease tags such asv0.2.0-rc.1leave it alone); - a promotion of the hosted service to production: bifrost-service’s
Promote to production fast-forwards
docs-productiontomaster.
A push to master or a pull request that touches docs/ builds the site
without deploying it, so a broken link or page fails the check before it
merges. Running the workflow from the Actions tab on docs-production redeploys
the current site; on any other branch it only builds.
So merge docs to master once what they describe is ready to ship with the
next release:
- CLI docs merge with the CLI change and go live with the next CLI release.
- Hosted-feature docs merge once the service change is on bifrost-service
main, and go live at the next promotion to production.
Two repository variables override the build target without a code change:
DOCS_SITE (default https://docs.slopcop.com) and DOCS_BASE (default /).
The custom domain itself is set in the repository’s Pages settings; a
GitHub Actions deployment needs no CNAME file.