The published documentation lives in site/:
index.html: installation, CLI and configuration reference.usage.html: runnable application examples and troubleshooting.styles.css: shared responsive styles, including dark mode.
The site uses static HTML and CSS, with no build dependencies. Use relative links so navigation also works under the repository's GitHub Pages URL prefix.
Run from the repository root:
python3 -m http.server 8000 --directory site --bind 127.0.0.1Open http://localhost:8000/ or http://localhost:8000/usage.html.
In another terminal, validate links, duplicate IDs and Python snippet syntax:
mkdir -p artifacts/logs
python3 scripts/check_site.py > artifacts/logs/site-check.log 2>&1The checker uses only Python's standard library (Python 3.10+). It does not check external URLs or execute the snippets. When changing runnable examples, also run them in a temporary project with NavConfig installed.
- In repository Settings → Pages → Build and deployment, select GitHub Actions as the source.
- Merge the site changes into
main. The Deploy GitHub Pages workflow validates the site, uploads onlysite/and deploys it to thegithub-pagesenvironment. - Open the URL reported by the deployment job. For this repository, the README uses https://phenobarbital.github.io/navconfig/; use the URL GitHub reports if repository capitalization or Pages configuration differs.
Pull requests validate the site without deployment permissions. You can also run
the workflow manually from Actions → Deploy GitHub Pages → Run workflow;
select main to publish. Other branches only run validation. If the repository
uses environment protection rules, github-pages must allow deployments from main.
See GitHub's custom Pages workflow documentation for repository setup and deployment requirements.