Ana içeriğe geç

GitHub Pages Yayınlama

Herkese açık dokümantasyon sitesi bir MkDocs Material statik sitesidir; GitHub Markdown dosya listesi veya README kopyası değildir.

URL İçerik
https://<org>.github.io/iqv-integration-api-go/ Dil seçim sayfası
.../tr/ Türkçe MkDocs sitesi
.../en/ İngilizce MkDocs sitesi

Project Pages /iqv-integration-api-go/ altında durur. İç bağlantılar ve asset’ler göreli yoldur. Kök /css veya /assets sabit kodlamayın.

Yayın nasıl çalışır

  1. Değişiklikler main’e girer (docs, mkdocs*.yml, requirements-docs.txt veya scripts/docs/**).
  2. .github/workflows/docs-pages.yml çalışır.
  3. Python 3.12 requirements-docs.txt kurar.
  4. scripts/docs/check_bilingual_structure.py docs/en ve docs/tr yol eşitliğini doğrular.
  5. mkdocs build --strict -f mkdocs.en.yml ve mkdocs.tr.yml.
  6. scripts/docs/assemble_pages_site.py site/index.html ve site/.nojekyll yazar.
  7. actions/configure-pages + actions/upload-pages-artifact + actions/deploy-pages site/ artifact’ini yayınlar.

PR ve feature-branch gönderimleri yalnız doğrulama çalıştırır (.github/workflows/docs.yml ve ci.yml içindeki docs işi). Pages yayınlamaz.

workflow_dispatch Pages işini elle çalıştırabilir. Yayın yine yalnız main üzerindendir.

Bir kez yapılması gereken GitHub Settings

  1. Depoyu GitHub’da açın.
  2. Settings → Pages.
  3. Build and deployment → Source = GitHub Actions (“Deploy from a branch” veya /docs değil).
  4. Kaydedin.
  5. main üzerinde ilk başarılı Docs Pages çalışmasından sonra github-pages ortamı oluşur; site URL’si iş özetinde görünür.

Source “Deploy from a branch” ve klasör /docs kalırsa ziyaretçi MkDocs teması yerine ham Markdown / Jekyll görür.

Yerel önizleme

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 site/index.html, site/en/ ve site/tr/ üretir. Serve bir seferde bir dili önizler.

Derleme nasıl doğrulanır

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 kip eksik nav dosyalarında ve birçok kırık bağlantıda başarısız olur.

Yayın hataları nerede incelenir

  • Actions → Docs Pages (derleme + yayın)
  • Actions → Docs (doğrulama)
  • Actions → CI → docs işi
  • github-pages ortamı yayın geçmişi

Açılış sayfasındaki sürüm metni docs/site-meta.yml dosyasından gelir.