Skip to content

Document GitHub docs workflow #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
johnnygreco merged 1 commit into from
Jun 24, 2026
Merged

Document GitHub docs workflow #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,30 @@ OpenShell as the runtime.

Use Python 3.10 or newer.

To preview the documentation locally:

```sh
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-docs.txt
zensical serve
```

The local preview runs at <http://localhost:8000>. To build the static site:
The local preview runs at <http://localhost:8000>. To run the same clean build
used by CI:

```sh
python scripts/render-dev-notes.py
zensical build --clean --strict
scripts/build-docs.sh
```

The generated site is written to `site/`.
The build script recreates `.venv-docs`, installs `requirements-docs.txt`,
renders Dev Notes metadata, and runs `zensical build --clean --strict`. The
generated site is written to `site/`.

GitHub Actions runs the docs workflow for every pull request and `main` push.
Pull requests validate the generated site without deploying. Pushes to `main`
and manual workflow dispatches from `main` publish `site/` to GitHub Pages
after validation passes.

### Dev Notes

Expand Down