Update mkdocs.yml #138
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: CI & Deploy (MkDocs Material / GitHub Pages) | |
| on: | |
| push: | |
| branches: [ "main", "*" ] | |
| pull_request: | |
| branches: [ "main" ] | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: pages-deploy | |
| cancel-in-progress: true | |
| jobs: | |
| lint: | |
| name: Markdown Lint | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repo | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| persist-credentials: false | |
| - name: Markdownlint | |
| uses: DavidAnson/markdownlint-cli2-action@v15 | |
| with: | |
| globs: | | |
| **/*.md | |
| !_sources/** | |
| linkcheck: | |
| name: Broken Link Check | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repo | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| persist-credentials: false | |
| - name: Cache lychee | |
| uses: actions/cache@v4 | |
| with: | |
| path: .lycheecache | |
| key: lychee-${{ runner.os }}-${{ hashFiles('.lychee.toml') }} | |
| - name: Run lychee | |
| uses: lycheeverse/lychee-action@v1 | |
| with: | |
| args: >- | |
| --config .lychee.toml | |
| --no-progress | |
| --accept 200,206,301,302,429 | |
| docs | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| build: | |
| name: Build Docs (with external sources) + Exports | |
| runs-on: ubuntu-latest | |
| needs: [lint, linkcheck] | |
| steps: | |
| - name: Checkout repo | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| persist-credentials: false | |
| # --- External sources checkout (read-only; skipped on forked PRs) --- | |
| - name: Checkout Rulebook | |
| if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false }} | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: International-Data-Spaces-Association/IDSA-Rulebook | |
| ref: main | |
| path: _sources/rulebook | |
| token: ${{ secrets.SOURCE_REPOS_PAT }} | |
| - name: Checkout IDS-RAM | |
| if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false }} | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: International-Data-Spaces-Association/IDS-RAM | |
| ref: main | |
| path: _sources/ram | |
| token: ${{ secrets.SOURCE_REPOS_PAT }} | |
| - name: Checkout Glossary | |
| if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false }} | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: International-Data-Spaces-Association/Glossary | |
| ref: main | |
| path: _sources/glossary | |
| token: ${{ secrets.SOURCE_REPOS_PAT }} | |
| - name: Checkout Manifesto | |
| if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false }} | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: International-Data-Spaces-Association/Manifesto-of-International-Data-Spaces | |
| ref: main | |
| path: _sources/manifesto | |
| token: ${{ secrets.SOURCE_REPOS_PAT }} | |
| - name: Setup Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.11" | |
| - name: Install dependencies (fresh) | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install --upgrade --no-cache-dir -r requirements.txt | |
| - name: Verify mkdocs + literate-nav in this env | |
| run: | | |
| python scripts/verify_env.py | |
| - name: Assemble external content & build merged SUMMARY | |
| run: | | |
| python scripts/sync_external_content.py | |
| - name: Debug show generated SUMMARY.md (first 200 lines) | |
| run: | | |
| sed -n '1,200p' docs/SUMMARY.md | |
| - name: Copy Manifesto README into docs/external | |
| shell: bash | |
| run: | | |
| mkdir -p docs/external/manifesto | |
| cp _sources/manifesto/README.md docs/external/manifesto/manifesto.md | |
| - name: Debug — list export directory | |
| if: always() | |
| shell: bash | |
| run: | | |
| set -euxo pipefail | |
| echo "PWD: $(pwd)" | |
| echo "Workspace: $GITHUB_WORKSPACE" | |
| echo "Export dir: ${EXPORT_DIR:-./docs}" | |
| dir="${EXPORT_DIR:-./docs}" | |
| if [ -d "$dir" ]; then | |
| echo "== ls -la ==" | |
| ls -la "$dir" | |
| echo | |
| echo "== tree (if available) ==" | |
| command -v tree >/dev/null 2>&1 && tree -a "$dir" || echo "tree not installed" | |
| echo | |
| echo "== du -h ==" | |
| du -h -d 2 "$dir" 2>/dev/null || du -h "$dir" | |
| echo | |
| echo "== file types (top 200) ==" | |
| find "$dir" -maxdepth 5 -type f -print0 | xargs -0 -n1 file | head -n 200 || true | |
| else | |
| echo "Directory does not exist: $dir" | |
| fi | |
| # --------------------------- | |
| # Export DOCX + PDF (main only) | |
| # --------------------------- | |
| - name: Compute export version | |
| id: exportver | |
| run: | | |
| SHORT_SHA="${GITHUB_SHA::7}" | |
| DATE="$(date -u +'%Y%m%d')" | |
| echo "version=${DATE}-${{ github.run_number }}-${SHORT_SHA}" >> "$GITHUB_OUTPUT" | |
| - name: Build export book markdown (ALL content) | |
| run: | | |
| mkdir -p exports | |
| python scripts/export_book.py \ | |
| --docs-dir docs \ | |
| --summary docs/SUMMARY.md \ | |
| --out exports/knowledge-base.md \ | |
| --title "IDSA Knowledge Base" \ | |
| --version "${{ steps.exportver.outputs.version }}" | |
| - name: Stage export media and rewrite image links | |
| run: | | |
| python scripts/export_stage_media.py \ | |
| --docs-dir docs \ | |
| --book exports/knowledge-base.md \ | |
| --out-book exports/knowledge-base.with-media.md \ | |
| --media-dir exports/media | |
| - name: Generate PDF cover page | |
| run: | | |
| cat > exports/cover.md <<'EOF' | |
| --- | |
| title: "IDSA Knowledge Base" | |
| subtitle: "Export" | |
| author: "International Data Spaces Association" | |
| date: "" | |
| license: "CC BY 4.0" | |
| citation: | | |
| IDSA Knowledge Base, version ${{ steps.exportver.outputs.version }}, International Data Spaces Association (IDSA) | |
| --- | |
| # IDSA Knowledge Base | |
| --- | |
| **Version:** ${{ steps.exportver.outputs.version }} | |
| **Generated:** $(date -u +'%Y-%m-%d') | |
| --- | |
| ## License | |
| {{ license }} | |
| ## How to Cite | |
| {{ citation }} | |
| --- | |
| \newpage | |
| EOF | |
| - name: Export DOCX (Pandoc) | |
| uses: docker://pandoc/core:3.9 | |
| with: | |
| args: >- | |
| exports/knowledge-base.with-media.md | |
| --from=markdown | |
| --standalone | |
| --toc | |
| --number-sections | |
| --reference-doc=assets/templates/reference.docx | |
| --resource-path=exports:exports/media:docs:docs/external:docs/assets | |
| --output=exports/knowledge-base-${{ steps.exportver.outputs.version }}.docx | |
| - name: Export PDF (Pandoc + LaTeX) | |
| uses: docker://pandoc/latex:3.9 | |
| with: | |
| args: >- | |
| exports/cover.md | |
| exports/knowledge-base.with-media.md | |
| --from=markdown | |
| --standalone | |
| --toc | |
| --number-sections | |
| --pdf-engine=xelatex | |
| -V papersize=a4 | |
| -V geometry:margin=2.5cm | |
| -V fontsize=11pt | |
| --resource-path=exports:exports/media:docs:docs/external:docs/assets | |
| --output=exports/knowledge-base-${{ steps.exportver.outputs.version }}.pdf | |
| - name: Debug count staged images and sample listing | |
| run: | | |
| ls -la exports/media | head -n 50 | |
| echo "Staged images:" $(ls -1 exports/media | wc -l) | |
| grep -R "!\[" -n exports/knowledge-base.with-media.md | head -n 20 | |
| - name: Publish exports into site downloads (latest + versioned) | |
| run: | | |
| mkdir -p docs/downloads | |
| cp "exports/knowledge-base-${{ steps.exportver.outputs.version }}.pdf" docs/downloads/knowledge-base-latest.pdf | |
| cp "exports/knowledge-base-${{ steps.exportver.outputs.version }}.docx" docs/downloads/knowledge-base-latest.docx | |
| cp "exports/knowledge-base-${{ steps.exportver.outputs.version }}.pdf" "docs/downloads/knowledge-base-${{ steps.exportver.outputs.version }}.pdf" | |
| cp "exports/knowledge-base-${{ steps.exportver.outputs.version }}.docx" "docs/downloads/knowledge-base-${{ steps.exportver.outputs.version }}.docx" | |
| - name: Upload versioned export artifact | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: knowledge-base-exports-${{ steps.exportver.outputs.version }} | |
| path: | | |
| exports/knowledge-base-${{ steps.exportver.outputs.version }}.pdf | |
| exports/knowledge-base-${{ steps.exportver.outputs.version }}.docx | |
| exports/knowledge-base.md | |
| - name: Debug — list export directory | |
| if: always() | |
| shell: bash | |
| run: | | |
| set -euxo pipefail | |
| echo "PWD: $(pwd)" | |
| echo "Workspace: $GITHUB_WORKSPACE" | |
| echo "Export dir: ${EXPORT_DIR:-./docs}" | |
| dir="${EXPORT_DIR:-./docs}" | |
| if [ -d "$dir" ]; then | |
| echo "== ls -la ==" | |
| ls -la "$dir" | |
| echo | |
| echo "== tree (if available) ==" | |
| command -v tree >/dev/null 2>&1 && tree -a "$dir" || echo "tree not installed" | |
| echo | |
| echo "== du -h ==" | |
| du -h -d 2 "$dir" 2>/dev/null || du -h "$dir" | |
| echo | |
| echo "== file types (top 200) ==" | |
| find "$dir" -maxdepth 5 -type f -print0 | xargs -0 -n1 file | head -n 200 || true | |
| else | |
| echo "Directory does not exist: $dir" | |
| fi | |
| # Build the HTML site (includes published downloads) | |
| - name: Build MkDocs (strict) | |
| run: python -m mkdocs build --strict | |
| - name: Upload artifact to Pages | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: site | |
| deploy: | |
| name: Deploy to GitHub Pages | |
| runs-on: ubuntu-latest | |
| needs: build | |
| if: ${{ github.ref == 'refs/heads/main' }} | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Configure Pages | |
| uses: actions/configure-pages@v5 | |
| - name: Deploy | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |