Skip to content

Contributing to Documentation

Note

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

Repo: github.com/evidential-org/evidential-docs

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

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

Local setup

  1. Install uv

  2. Clone and switch to source branch

git clone git@github.com:evidential-org/evidential-docs.git
cd evidential-docs
git checkout docs
  1. Install dependencies
uv sync
  1. Install precommit hooks to this repo
   uv run pre-commit install
  1. Preview locally
uv run mkdocs serve
# Default served at http://127.0.0.1:8000; use -a host:port to customize

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