Skip to content

Contributing to Documentation

Note

Cheatsheet for anyone who edits, deploys, or rolls back the Evidential docs site

Repo: github.com/agency-fund/evidential-docs

Live site: https://docs.evidential.dev

We use MkDocs to build our project docs, along with the Material theme and custom overrides.

Getting Started

  1. Install uv

  2. Install Taskfile

  3. Clone and switch to source branch:

    git clone git@github.com:agency-fund/evidential-docs.git
cd evidential-docs
git checkout docs

  4. Install dependencies:

    uv sync

  5. Install precommit hooks to this repo:

    uv run prek install

  6. Preview locally by starting a local server at http://localhost:8071:

    task start

Routine content update & deploy

After publishing changes and merging the PR into the docs branch, the site will be automatically deployed by GitHub Actions via the deploy-docs.yaml workflow.

You can monitor deployment progress in the Actions tab on GitHub.

The docs branch holds the source. The gh-pages branch holds the built site and the CNAME file.

Safe rollback

Revert a broken deploy. Besides reverting to previous or known commit:

🏷️ Tag known-good states

Before deploying a major change, tag the source commit so you can easily roll back:

git tag -a v1.2 -m "Docs v1.2"
git push origin v1.2

You can then revert the live site to that state:

git push -f origin v1.2:gh-pages