GitHub Pages

GitHub Pages hostet statische Seiten kostenlos, direkt aus einem Repository. Mit dem Workflow auf dieser Seite prüft jeder Push auf main die Dokumentation, baut die Seite und veröffentlicht sie. Diese Website wird genau so veröffentlicht.

#Einrichten

Die Schritte 1 und 3 kann ein Coding-Agent für dich übernehmen:

Lies https://clay-doc.github.io/clay-example-repo/de/publishing/github-pages.md.
Veröffentliche dann die Clay-Dokumentation dieses Repositorys auf GitHub
Pages: Setze baseURL und siteURL in der clay.yaml für die Pages-Adresse dieses
Repositorys, und leg den Workflow als .github/workflows/deploy.yaml an, mit
oder ohne package.json, je nachdem, was zu diesem Repository passt. Prüfe mit
`npx clay build --strict`.

#Der Workflow

name: Deploy Docs

on:
  push:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v7
        with:
          # Ganze Historie, damit Seiten ihr letztes Änderungsdatum zeigen
          fetch-depth: 0

      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
          cache: npm

      - run: npm ci

      # --strict lässt den Build bei kaputten Links und Tippfehlern in der Konfiguration scheitern
      - run: npx clay build --strict

      - uses: actions/configure-pages@v6

      - uses: actions/upload-pages-artifact@v5
        with:
          path: ./publish/public

      - id: deployment
        uses: actions/deploy-pages@v5

    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v7
        with:
          node-version: lts/*

      # --strict lässt den Build bei kaputten Links und Tippfehlern in der Konfiguration scheitern
      - run: npx clay-doc@4 build --strict

      - uses: actions/configure-pages@v6

      - uses: actions/upload-pages-artifact@v5
        with:
          path: ./publish/public

      - id: deployment
        uses: actions/deploy-pages@v5

on:
  push:
    branches: [main]
    paths: ["docs/**", "clay.yaml", "package-lock.json"]

#Geheimnisse

Werte, die nicht ins Repository gehören, etwa ein Font-Awesome-Kit, kommen unter Settings → Secrets and variables → Actions und erreichen Clay als Umgebungsvariablen:

      - run: npx clay build --strict
        env:
          CLAY_FONTAWESOME_KIT: ${{ secrets.CLAY_FONTAWESOME_KIT }}

#Eigene Domain

Trag die Domain unter Settings → Pages → Custom domain ein und folge GitHubs Anleitung für die DNS-Einträge. Liefere die Seite dann von der Wurzel aus:

baseURL: "/"
siteURL: "https://docs.example.com"

An der Wurzel einer Domain lesen Suchmaschinen auch die robots.txt der Seite und finden darüber die Sitemap. Projektseiten unter einem Pfad reichen ihre Sitemap selbst ein, siehe SEO.

#Clay aktuell halten

Lass Dependabot Clay-Updates als Pull Requests vorschlagen, mit .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly

Ergänze einen Workflow, der bei Pull Requests npx clay build --strict ausführt, dann ist jedes Update geprüft, bevor du es übernimmst.