Thanks for helping improve the Evidential docs! Whether you’re fixing a typo or writing a new guide, every change goes
through a pull request on agency-fund/evidential-site, where the docs
live in sites/docs/. Automated checks run on every pull request, and a reviewer reads it before it’s merged, so you
don’t need to get everything right on your own.
The site is built with Nimbus, a documentation framework based on Astro. Pages are MDX files: Markdown that can also use a few components, such as callouts and expandable sections.
Who Can Contribute
Anyone can propose a change.
- Team members with push access to evidential-site push a branch to the repository and open a pull request from it. These pull requests get the automated checks and a Preview: a copy of the whole site with your changes, at its own address, linked from the pull request.
- Everyone else works from a fork
of evidential-site and opens a pull request from it. Pull requests from forks get the same checks but no Preview, so
check your change locally with
task docs:start(see below). The first time you contribute, a maintainer may need to approve the checks before they run.
For anything larger than a fix, such as a new page or a reorganized section, it helps to reach out to the team first, or to open an early draft pull request.
Quick Edits on GitHub
For a typo, a broken link, or a sentence that needs rewording, you can make the whole change in your browser, with no local setup:
-
Find the page’s file
Open the page’s file under
sites/docs/src/content/docs/. A page’s path there matches its URL:/concepts/how-evidential-works/isconcepts/how-evidential-works.mdx. -
Edit it
Select Edit this file (the pencil icon). If you don’t have push access, GitHub creates a fork for you.
-
Propose the change
Select Commit changes, describe what you changed, and choose to create a new branch and start a pull request. Without push access, the button reads Propose changes.
-
Open the pull request
GitHub shows the pull request form. Add a sentence on why the change helps, then select Create pull request.
The same checks run as for any other pull request, and a reviewer takes it from there.
Set Up Your Computer
For anything more than a quick edit, work locally so you can see your changes as you make them.
-
Install pnpm, Task, prek, and the GitHub CLI (
gh). pnpm downloads the version of Node.js the site needs, so you don’t need to install it. -
Clone the repository (or your fork) and install its dependencies and git hooks:
git clone git@github.com:agency-fund/evidential-site.git cd evidential-site task setup -
Start the docs on a local server at http://localhost:4322:
task docs:startPages reload as you save them. Search covers the site as of the last build; run
task docs:buildto include later edits.
Run task --list for the other tasks.
Make a Change with a Pull Request
-
Create a branch
Start from an up-to-date
main:git switch main git pull git switch -c docs/describe-your-change -
Edit the pages
Pages are in
sites/docs/src/content/docs/. To add a page, create an.mdxfile in the folder for its section (see Writing Pages). -
Preview your change locally
With
task docs:startrunning, open http://localhost:4322 and read your change as a reader would. -
Run the checks
task docs:build task docs:check task linttask docs:checktype-checks the site, checks that its links resolve, and lints the content. It checks links against the last build, so runtask docs:buildfirst, especially after adding or moving pages.task lintruns the repository’s git hooks on every file; they also run on each commit. -
Commit and push
git add sites/docs git commit -m "Explain how to rotate API keys" git push -u origin docs/describe-your-change -
Open a pull request
Use the GitHub CLI to open a pull request against
main:gh pr create --base mainIt asks for a title and a description: say what you changed and why, and link any related issue. Add
--webto finish the pull request in your browser instead. -
Read your Preview
Once the checks pass, a bot comments a link to your Preview on the pull request: the whole site, built with your changes. Each later push updates the same Preview and comment. A new Preview can take a minute to start serving.
Previews are made for pull requests from branches in evidential-site that change the pages,
public/, the site’s configuration, or the API reference. Pull requests from forks don’t get one. -
Address review
A reviewer may suggest changes. Push more commits to the same branch; the checks and Preview update on their own.
-
Merge
Once the checks pass and the pull request is approved, it can be merged into
main.
After the merge, the site’s production version deploys automatically, usually within a few minutes. The pull request’s Preview is deleted when the pull request is merged or closed.
Writing Pages
Where Things Live
All paths are under sites/docs/.
| What | Where |
|---|---|
| Pages | src/content/docs/, as .mdx files. A file’s path is its URL; index.mdx is the home page. |
| Sidebar | Built from the folders; sidebar.order in a page’s frontmatter sets its place in its section. |
| Images | Beside the page that uses them. |
| API reference overview | src/api/overview.md, the introduction at the top of the API reference. |
| API reference operations | src/api/openapi.json, generated from the live API’s spec. Don’t edit it by hand. |
| Files served as-is | public/, such as the onboarding video’s poster frame. |
The API reference is built from the Evidential API’s OpenAPI spec. Descriptions of endpoints and fields come from the
API itself, so change those in evidential-be. To bring the reference
up to date with the live API, run task docs:openapi and commit both files it changes. The
docs README covers the
details.
Conventions
-
Title: every page needs a
titlein its frontmatter. It becomes the page heading, so don’t repeat it as a#heading in the body.--- title: "Analyzing Results" --- The first paragraph of the page. -
Callouts:
:::note,:::tip,:::caution, and:::danger, each with an optional title in brackets::::tip[Keep pull requests focused] One change per pull request is quicker to review. :::Pick the type by what happens if the reader skips it:
:::notefor background or context the reader can skip.:::tipfor a recommendation or a better way.:::cautionfor something that fails, breaks, or surprises if ignored.:::dangerfor data loss, security, or irreversible production effects.
Don’t use
info,warning, orimportant. Always give a caution or danger a title phrased as the takeaway, such as:::caution[CI rejects model changes without migrations]; give a note or tip a title when its body is longer than about two lines. Avoid bare titles like “Important”, and emoji. Keep each callout to one to four sentences, use at most about three on a page, and put it beside the step it qualifies. Write “Note:” asides as callouts rather than blockquotes or bold lead-ins, and don’t separate sections with horizontal rules. -
Expandable sections:
<Accordion>, with an<AccordionTrigger>for the heading and<AccordionContent>for what it reveals. -
Diagrams: Mermaid, written as
<pre class="mermaid">{`…`}</pre>with the diagram between the backticks. -
Images: put the file beside the page and link it relatively, such as
, so Astro optimizes it. -
Steps: wrap a numbered list in
<Steps>to show it as a sequence of steps, as on this page.
How Deploys Work
The docs are a static site served by Cloudflare Workers. GitHub Actions
(.github/workflows/docs.yaml) checks every pull request and deploys each merge into main.
You can follow each run in the Actions tab, or from the checks on the pull request.