Development

Development

Day-to-day work in this repository: the common tasks and the conventions to follow. See Getting-Started for first-time setup.

Tooling

There is no linter, formatter, or test suite configured — package.json defines only the five Astro scripts. The build is the only automated check, and it is the one the deploy workflow runs. Before opening a pull request, confirm npm run build succeeds.

.gitignore covers node_modules/, dist/, .astro/, and .wrangler/. Never commit a build output.

Adding a page

1. Create src/pages/<name>.astro. The filename becomes the route.
2. Import and wrap the body in <Layout>, passing at minimum a title and, for anything public-facing, a description.
3. Reuse the container and section conventions in Styling so the page matches the rest of the site.
4. If it should appear in the header, add an entry to the leftNav array in Layout.astro, with an icon path in navIcon. If it should appear in the footer, add a list item in the relevant footer column.

Editing copy

Most copy is in a frontmatter array rather than in markup — see Content-and-Pages for the exact constant per section. Editing the array is almost always the right move; editing the markup that renders it duplicates content that was deliberately hoisted.

Adding an image

1. Put the file in public/. Product screenshots are .webp.
2. Reference it by root-relative path, so public/foo.webp becomes /foo.webp.
3. Give it real width and height attributes to avoid layout shift, and loading="lazy" for anything below the fold.
4. Add data-lightbox if it should be zoomable, and class="cursor-zoom-in" so the cursor advertises it. The layout's lightbox script picks it up automatically.
5. Write a meaningful alt, or alt="" if the image is decorative.

Adding a diagram

Import Mermaid.astro, define the diagram source as a template literal in the page frontmatter, and pass it as code with an optional caption. Diagrams render in the browser from a CDN import, so check them with npm run dev rather than assuming a successful build means the diagram is valid — a Mermaid syntax error surfaces only at runtime, in the browser console.

Refreshing the API reference

/docs renders public/openapi.json. The openapi-sync workflow regenerates it from the reportmate-api source every day and deploys when it changed, so it needs no hand edits. To pick up an API change sooner, run the workflow on main from the Actions tab (workflow_dispatch). The page itself needs no change.

Bumping the pinned Stoplight Elements version in docs.astro means updating the version in both the stylesheet and script URLs and recomputing both Subresource Integrity hashes. A stale integrity value blocks the resource silently, leaving an empty docs panel.

Dependency and action updates

Dependencies are few — Astro, the Tailwind integration, and Tailwind itself. Update them together and commit the resulting package-lock.json, since the workflow runs npm ci and will fail if the lockfile is out of step with package.json.

GitHub Actions are pinned by commit SHA with the version tag in a trailing comment; update both together.

Contributing

Contribution terms are org-wide and live in the .github repository: the CONTRIBUTING guide and the CLA. In short, branch from the default branch, keep a pull request to one change, make sure the build passes, and sign off every commit with git commit -s.

This repository is MIT licensed.