Skip to content

Hosting Project Documentation

Project documentation turns a folder of files into a clean, navigable website that can be used to present and share analytics projects.

Professional Purpose

Hosting documentation as a website helps:

  • Share project information with a single link (no downloads needed)
  • Keep instructions, examples, and policies close to the code
  • Document decisions and changes over time
  • Demonstrate professional practice (clear documentation is a necessary part of project quality)

In these projects, documentation lives in the docs/ folder and is built with our documentation tool.

How It Works

  • We write pages as Markdown files in docs/
  • a config file in the project root defines the site title, theme, and navigation (nav)
  • The documentation builder builds a static website into a site/ folder (as generated output)
  • GitHub Pages hosts site/ as a public website
  • GitHub Actions can build and deploy the site automatically on every push

Prerequisites for a Documentation Site

  • The repository must have:
  • docs/ folder
  • zensical.toml
  • The documentation builder tool is installed in the project environment (via pyproject.toml)
  • The site is built with commands from the repo root using uv run ...

Step 1: Enable GitHub Pages

See Configure Repository Settings.

Step 2: Configure a GitHub Actions Workflow

See examples of automatic GitHub actions in this project. We first ensure the site builds in the CI (continuous integration) step and then deploy the docs in a separate step.

  • CI: .github/workflows/ci-python-zensical.yml
  • Deploy: .github/workflows/deploy-zensical.yml

Step 3: Preview the Docs Locally

From the repo root:

uv run python -m zensical build
uv run python -m zensical serve

Serving the docs will launch a local web server. Open a browser to or whatever URL is provided. To stop the server, press Ctrl + C in the terminal.

The build will verify that:

  • all files in docs/ are also in the navigation
  • all files listed in zensical.toml nav are also in docs/.

Step 4: Trigger the First Deploy (Automatically)

When we save progress, the two actions above will be triggered.

Save progress frequently. Some tools may make changes; you may need to re-run git add and commit to ensure everything gets committed before pushing.

git add -A
git commit -m "your message here"

# repeat if changes were made (try the UP ARROW)
git add -A
git commit -m "your message here"

git push -u origin main

Troubleshooting

Site shows a 404 (file not found) error

  • Confirm Settings / Pages / Source is set to GitHub Actions
  • Confirm the documentation workflow run succeeded (see the GitHub repo Actions tab)
  • Confirm the site builds locally without errors:
uv run python -m zensical build --strict

Build fails with "file not found"

  • Check paths in zensical.toml, especially under the nav: section
  • Confirm the referenced page exists in docs/
  • Verify spelling and capitalization exactly match the file name

Changed docs but site did not update

  • Confirm changes were pushed to the main branch
  • Check the GitHub repo Actions tab to verify that a workflow run was triggered
  • If needed, re-run the workflow manually from the Actions tab

Powerful tools make professional projects possible from the beginning.

◄ Back to 🏠 Guide Home