Skip to content

Publishing Documentation

The public documentation site is a MkDocs Material static site, not a GitHub Markdown file listing and not a copy of the README.

URL Content
https://<org>.github.io/iqv-integration-api-go/ Language landing
.../tr/ Turkish MkDocs site
.../en/ English MkDocs site

Project Pages sit under /iqv-integration-api-go/. Internal links and assets use relative paths. Do not hard-code site-root /css or /assets.

How publishing works

  1. Changes land on main (docs, mkdocs*.yml, requirements-docs.txt, or scripts/docs/**).
  2. Workflow .github/workflows/docs-pages.yml runs.
  3. Python 3.12 installs requirements-docs.txt.
  4. scripts/docs/check_bilingual_structure.py verifies docs/en and docs/tr path parity.
  5. mkdocs build --strict -f mkdocs.en.yml and mkdocs.tr.yml.
  6. scripts/docs/assemble_pages_site.py writes site/index.html and site/.nojekyll.
  7. actions/configure-pages + actions/upload-pages-artifact + actions/deploy-pages publish the site/ artifact.

PR and feature-branch pushes run validation only (.github/workflows/docs.yml and the docs job in ci.yml). They do not deploy Pages.

workflow_dispatch can run the Pages workflow manually. Deploy still occurs only from main.

GitHub Settings you must set once

  1. Open the repository on GitHub.
  2. Settings → Pages.
  3. Build and deployment → Source = GitHub Actions (not “Deploy from a branch”, not /docs).
  4. Save.
  5. After the first successful Docs Pages run on main, the github-pages environment appears and the site URL is shown on the workflow summary.

If Source remains “Deploy from a branch” and the branch folder is /docs, visitors see raw Markdown / Jekyll output instead of the MkDocs theme.

Local preview

powershell python -m venv .venv-docs .\.venv-docs\Scripts\pip install -r requirements-docs.txt .\scripts\windows\docs-build.ps1 .\scripts\windows\docs-serve.ps1 -Language en .\scripts\windows\docs-serve.ps1 -Language tr

bash python3 -m venv .venv-docs source .venv-docs/bin/activate pip install -r requirements-docs.txt ./scripts/linux/docs-build.sh ./scripts/linux/docs-serve.sh en ./scripts/linux/docs-serve.sh tr

docs-build produces site/index.html, site/en/, and site/tr/. Serve still previews one language at a time.

How to verify a build

text python scripts/docs/check_bilingual_structure.py mkdocs build --strict -f mkdocs.en.yml mkdocs build --strict -f mkdocs.tr.yml python scripts/docs/assemble_pages_site.py

Strict mode fails on missing nav files and many broken links.

Where to inspect deployment failures

  • Actions → Docs Pages (build + deploy)
  • Actions → Docs (validation)
  • Actions → CI → docs job
  • Environment github-pages deployment history

Version strings on the landing page come from docs/site-meta.yml.