---
title: "Contribute to the docs"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.evidential.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/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](https://nimbus-docs.com), a documentation framework based on
[Astro](https://astro.build). 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
  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](https://docs.evidential.dev/contact/) 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/`](https://github.com/agency-fund/evidential-site/tree/main/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](https://pnpm.io/installation), [Task](https://taskfile.dev/docs/installation),
   [prek](https://prek.j178.dev), and the [GitHub CLI](https://cli.github.com) (`gh`). pnpm downloads the version of Node.js the site needs, so you don't need to install it.

1. Clone the repository (or your fork) and install its dependencies and git hooks:

   ```bash
   git clone git@github.com:agency-fund/evidential-site.git
   cd evidential-site
   task setup
   ```

1. Start the docs on a local server at [http://localhost:4322](http://localhost:4322):

   ```bash
   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`:

   ```bash
   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](#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**

   ```bash
   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**

   ```bash
   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](https://cli.github.com) to open a pull request against `main`:

   ```bash
   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](https://docs.evidential.dev/api/).              |
| 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](https://github.com/agency-fund/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](https://github.com/agency-fund/evidential-site/blob/main/sites/docs/README.md#layout) 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.

  ```mdx
  ---
  title: "Analyzing Results"
  ---

  The first paragraph of the page.
  ```

- **Callouts**: `:::note`, `:::tip`, `:::caution`, and `:::danger`, each with an optional title in brackets:

  ```mdx
  :::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](https://developers.cloudflare.com/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.

Source: https://docs.evidential.dev/develop/guides/contribute-to-the-docs/index.mdx
