Publish the docs to a static host¶

The repository is private, so the Docs GitHub Actions workflow builds the MkDocs site in GitHub and deploys the generated static files to a server over SSH.

This page intentionally uses placeholders. Do not commit private hostnames, domains, IP addresses, usernames, or filesystem paths to the repository.

Create a writable docs directory on the server¶

Create a directory for the static site and make it writable by the deploy user:

sudo install -d -o <deploy-user> -g <deploy-user> /var/www/audiotext-docs

You can use any directory. Store the real path in the DOCS_REMOTE_PATH repository variable instead of committing it.

Point the reverse proxy at the static directory¶

For Caddy, use a site block like this:

<docs-hostname> {
    root * /var/www/audiotext-docs
    encode zstd gzip
    file_server
}

Make sure DNS for <docs-hostname> points to the server before enabling TLS.

Add GitHub repository variables and secrets¶

In GitHub, open Settings > Secrets and variables > Actions.

Add these repository variables:

Variable	Example
`DOCS_SSH_HOST`	`<server-hostname-or-ip>`
`DOCS_SSH_USER`	`<deploy-user>`
`DOCS_SSH_PORT`	`22`
`DOCS_REMOTE_PATH`	`/var/www/audiotext-docs`

Add these repository secrets:

Secret	Value
`DOCS_SSH_PRIVATE_KEY`	Private SSH key that can write to the docs directory
`DOCS_SSH_KNOWN_HOSTS`	Host key line for the server

Create the known-hosts value from your machine:

ssh-keyscan -p 22 <server-hostname-or-ip>

Store the output as DOCS_SSH_KNOWN_HOSTS. This avoids accepting an unknown SSH host key inside the GitHub runner.

If these values are missing, the workflow still builds the docs artifact and skips the server deploy with a notice.

Run the workflow¶

The workflow runs on pushes to main that change docs, mkdocs.yml, package metadata, lockfiles, or API-reference source modules. You can also run it manually from the Actions tab.

After it finishes, open your configured docs URL.

Keep private-repo docs safe¶

The source repository is private, but the rendered docs URL may be public depending on DNS and reverse-proxy rules. Do not put secrets, private tokens, private audio, transcript examples, customer/company data, private hostnames, or personal infrastructure details in the docs.

Build the same site locally¶

Run:

uv sync --extra docs
uv run mkdocs build --strict

For local browsing:

uv run mkdocs serve