Skip to content

GitHub Pages documentation site

This repository ships a professional static documentation site powered by MkDocs Material and GitHub Pages.

Local preview

Install the documentation toolchain:

python -m pip install -r docs/requirements.txt

Run the local server:

mkdocs serve

Build the production site exactly like CI:

mkdocs build --strict

GitHub Pages deployment

The workflow lives in .github/workflows/pages.yml.

It runs for:

  • pull requests that change docs/**, mkdocs.yml, or the workflow itself;
  • pushes to master that change documentation files;
  • manual workflow_dispatch runs.

Pull requests build the site but do not deploy. Pushes to master upload the generated site/ artifact and deploy it through GitHub Pages.

Repository settings

In GitHub, enable Pages once:

  1. Open Settings -> Pages.
  2. Set Build and deployment to GitHub Actions.
  3. Save the setting.

No PyPI token, GitHub token, database credential, or external service secret is required for the docs deploy.

The public site uses curated navigation:

  • onboarding and CLI docs first;
  • core concepts next;
  • connector guides;
  • source -> sink implementation guides;
  • operations and production readiness;
  • developer docs.

Older rollout notes and provider-specific implementation history remain in the repository, but they are intentionally not prominent in the public navigation.

Style policy

The site uses a light, quiet interface inspired by modern documentation products:

  • flat surfaces instead of heavy cards;
  • high-contrast text on white/off-white backgrounds;
  • subdued borders;
  • responsive grids that avoid narrow, tall panels;
  • copyable code blocks and searchable navigation.

Troubleshooting

mkdocs build --strict fails with a missing nav page

Confirm the file exists under docs/ and the nav path in mkdocs.yml is relative to docs/, not the repository root.

GitHub Pages deploy is skipped on a pull request

That is expected. Pull requests build the site only. Deployment happens after merge or push to master.

GitHub Pages shows a 404

Check that repository Pages settings use GitHub Actions as the source and that the latest docs workflow run completed successfully on master.