Skip to content

Contribute to the docs

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:

  1. 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/ is concepts/how-evidential-works.mdx.

  2. Edit it

    Select Edit this file (the pencil icon). If you don’t have push access, GitHub creates a fork for you.

  3. 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.

  4. 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.

  1. 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.

  2. 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
  3. Start the docs on a local server at http://localhost:4322:

    task docs:start

    Pages reload as you save them. Search covers the site as of the last build; run task docs:build to include later edits.

Run task --list for the other tasks.

Make a Change with a Pull Request

  1. Create a branch

    Start from an up-to-date main:

    git switch main
    git pull
    git switch -c docs/describe-your-change
  2. Edit the pages

    Pages are in sites/docs/src/content/docs/. To add a page, create an .mdx file in the folder for its section (see Writing Pages).

  3. Preview your change locally

    With task docs:start running, open http://localhost:4322 and read your change as a reader would.

  4. Run the checks

    task docs:build
    task docs:check
    task lint

    task docs:check type-checks the site, checks that its links resolve, and lints the content. It checks links against the last build, so run task docs:build first, especially after adding or moving pages. task lint runs the repository’s git hooks on every file; they also run on each commit.

  5. Commit and push

    git add sites/docs
    git commit -m "Explain how to rotate API keys"
    git push -u origin docs/describe-your-change
  6. Open a pull request

    Use the GitHub CLI to open a pull request against main:

    gh pr create --base main

    It asks for a title and a description: say what you changed and why, and link any related issue. Add --web to finish the pull request in your browser instead.

  7. 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.

  8. Address review

    A reviewer may suggest changes. Push more commits to the same branch; the checks and Preview update on their own.

  9. 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 title in 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:

    • :::note for background or context the reader can skip.
    • :::tip for a recommendation or a better way.
    • :::caution for something that fails, breaks, or surprises if ignored.
    • :::danger for data loss, security, or irreversible production effects.

    Don’t use info, warning, or important. 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 ![Architecture](./architecture.png), 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.

Type to search…

↑↓ navigate↵ selectEsc close