From 60fedcc082999c43f20d2540bec0ad718d53c1a8 Mon Sep 17 00:00:00 2001 From: Sebastian Steinbuss <23654606+ssteinbuss@users.noreply.github.com> Date: Fri, 8 May 2026 12:42:30 +0200 Subject: [PATCH 1/2] update release flow --- .github/workflows/reusable-release-export.yml | 82 +++++++++++-------- .../.github/workflows/release.yml | 65 +++++++++++++-- 2 files changed, 110 insertions(+), 37 deletions(-) diff --git a/.github/workflows/reusable-release-export.yml b/.github/workflows/reusable-release-export.yml index 9e9d55c..56b7197 100644 --- a/.github/workflows/reusable-release-export.yml +++ b/.github/workflows/reusable-release-export.yml @@ -1,47 +1,65 @@ -name: Reusable Release Export +name: Release (Export + Cover) on: - workflow_call: - inputs: - content_dir: - required: true - type: string - summary_path: - required: true - type: string - output_basename: - required: false - type: string - default: documentation + release: + types: [published] + workflow_dispatch: permissions: contents: write jobs: export: + uses: International-Data-Spaces-Association/.github/.github/workflows/reusable-release-export.yml@main + with: + summary_path: summary.md + output_basename: knowledge-base + papersize: a4 + margin: 2.5cm + fontsize: 11pt + mainfont: Noto Sans + sansfont: Noto Sans + monofont: Fira Code + # optionally override: + # pandoc_image: ghcr.io//pandoc-latex-fonts:3.9 + + add-cover-and-publish: + needs: export runs-on: ubuntu-latest + steps: - - uses: actions/checkout@v4 - - uses: actions/checkout@v4 + - name: Checkout repository (to access assets/cover.pdf) + uses: actions/checkout@v4 + + - name: Download export artifacts + uses: actions/download-artifact@v4 with: - repository: International-Data-Spaces-Association/.github - path: _shared - - name: Install Pandoc + TeX - run: | - sudo apt-get update - sudo apt-get install -y pandoc texlive-xetex texlive-fonts-recommended texlive-latex-extra - - name: Assemble - run: | - python3 _shared/scripts/assemble_from_summary.py --summary "${{ inputs.summary_path }}" --out combined.md --fail-on-missing - - name: Build + name: release-export + path: exports + + - name: Merge cover + body PDF (create additional artefact) run: | - TAG="${{ github.event.release.tag_name }}" - BASENAME="${{ inputs.output_basename }}" - pandoc combined.md --from gfm --resource-path=.:"${{ inputs.content_dir }}" --reference-doc=_shared/assets/reference.docx -o "${BASENAME}-${TAG}.docx" - pandoc combined.md --from gfm --resource-path=.:"${{ inputs.content_dir }}" --pdf-engine=xelatex -o "${BASENAME}-${TAG}.pdf" - - name: Upload + python -m pip install --upgrade pip + python -m pip install pypdf + python - <<'PY' + from pypdf import PdfWriter + + cover = "assets/cover.pdf" + body = "exports/knowledge-base.pdf" + out = "exports/knowledge-base-with-cover.pdf" + + writer = PdfWriter() + writer.append(cover) # cover can be 1 or multiple pages + writer.append(body) + writer.write(out) + print(f"Created {out}") + PY + # pypdf supports merging by appending PDFs via PdfWriter.append() and writing the output. [2](https://bing.com/search?q=material+for+mkdocs+custom+404+page+setup)[3](https://squidfunk.github.io/mkdocs-material/customization/) + + - name: Upload release assets (keep ALL artefacts) uses: softprops/action-gh-release@v2 with: files: | - ${{ inputs.output_basename }}-${{ github.event.release.tag_name }}.pdf - ${{ inputs.output_basename }}-${{ github.event.release.tag_name }}.docx + exports/knowledge-base.pdf + exports/knowledge-base-with-cover.pdf + exports/knowledge-base.docx \ No newline at end of file diff --git a/examples/consumer-repo/.github/workflows/release.yml b/examples/consumer-repo/.github/workflows/release.yml index bca19cb..a07ed4a 100644 --- a/examples/consumer-repo/.github/workflows/release.yml +++ b/examples/consumer-repo/.github/workflows/release.yml @@ -1,13 +1,68 @@ -name: Release export +name: Release (Export + Cover) + on: release: - types: [ published ] + types: [published] + workflow_dispatch: + permissions: contents: write + +env: + BASENAME: documentation # <-- this is the directory/basename you mean + EXPORT_DIR: dist # where we download artifacts to + jobs: export: uses: International-Data-Spaces-Association/.github/.github/workflows/reusable-release-export.yml@main with: - content_dir: ${{ vars.CONTENT_DIR }} - summary_path: ${{ vars.SUMMARY_PATH }} - output_basename: ${{ github.event.repository.name }} + summary_path: summary.md + output_basename: documentation # must match BASENAME above + + add-cover-and-publish: + needs: export + runs-on: ubuntu-latest + + steps: + - name: Checkout repository (for assets/cover.pdf) + uses: actions/checkout@v4 + + - name: Download export artifacts + uses: actions/download-artifact@v4 + with: + name: release-export + path: ${{ env.EXPORT_DIR }} + + - name: Verify expected files exist + run: | + ls -la "${{ env.EXPORT_DIR }}" + test -f "assets/cover.pdf" + test -f "${{ env.EXPORT_DIR }}/${{ env.BASENAME }}.pdf" + test -f "${{ env.EXPORT_DIR }}/${{ env.BASENAME }}.docx" + + - name: Merge cover + body PDF (create additional artifact) + run: | + python -m pip install --upgrade pip + python -m pip install pypdf + python - <<'PY' + from pypdf import PdfWriter + + cover = "assets/cover.pdf" + body = "${{ env.EXPORT_DIR }}/${{ env.BASENAME }}.pdf" + out = "${{ env.EXPORT_DIR }}/${{ env.BASENAME }}-with-cover.pdf" + + writer = PdfWriter() + writer.append(cover) # cover can be 1 or multiple pages + writer.append(body) + writer.write(out) + print(f"Created {out}") + PY + # pypdf merges PDFs by appending inputs with PdfWriter.append() and writing output. [2](https://bing.com/search?q=material+for+mkdocs+custom+404+page+setup) + + - name: Upload release assets (keep ALL artifacts) + uses: softprops/action-gh-release@v2 + with: + files: | + ${{ env.EXPORT_DIR }}/${{ env.BASENAME }}.pdf + ${{ env.EXPORT_DIR }}/${{ env.BASENAME }}-with-cover.pdf + ${{ env.EXPORT_DIR }}/${{ env.BASENAME }}.docx \ No newline at end of file From 495b92a742a033081aaaa7c22666f71a215ef1e8 Mon Sep 17 00:00:00 2001 From: Sebastian Steinbuss <23654606+ssteinbuss@users.noreply.github.com> Date: Fri, 8 May 2026 12:45:34 +0200 Subject: [PATCH 2/2] Update reusable-release-export.yml --- .github/workflows/reusable-release-export.yml | 146 ++++++++++++------ 1 file changed, 100 insertions(+), 46 deletions(-) diff --git a/.github/workflows/reusable-release-export.yml b/.github/workflows/reusable-release-export.yml index 56b7197..940b47a 100644 --- a/.github/workflows/reusable-release-export.yml +++ b/.github/workflows/reusable-release-export.yml @@ -1,65 +1,119 @@ -name: Release (Export + Cover) +name: Reusable Release Export (Pandoc in Docker) on: - release: - types: [published] - workflow_dispatch: + workflow_call: + inputs: + summary_path: + description: "Path to summary.md in the caller repository" + required: true + type: string + + content_dir: + description: "Working directory of the caller repository content" + required: false + type: string + default: . + + output_basename: + description: "Base name for produced artifacts (without extension)" + required: false + type: string + default: documentation + + # Prebuilt image containing pandoc + xelatex + fonts + pandoc_image: + required: false + type: string + default: ghcr.io//pandoc-latex-fonts:3.9 + + # Knowledge Base PDF defaults + papersize: + required: false + type: string + default: a4 + margin: + required: false + type: string + default: 2.5cm + fontsize: + required: false + type: string + default: 11pt + mainfont: + required: false + type: string + default: Noto Sans + sansfont: + required: false + type: string + default: Noto Sans + monofont: + required: false + type: string + default: Fira Code permissions: - contents: write + contents: read jobs: export: - uses: International-Data-Spaces-Association/.github/.github/workflows/reusable-release-export.yml@main - with: - summary_path: summary.md - output_basename: knowledge-base - papersize: a4 - margin: 2.5cm - fontsize: 11pt - mainfont: Noto Sans - sansfont: Noto Sans - monofont: Fira Code - # optionally override: - # pandoc_image: ghcr.io//pandoc-latex-fonts:3.9 - - add-cover-and-publish: - needs: export runs-on: ubuntu-latest steps: - - name: Checkout repository (to access assets/cover.pdf) + - name: Checkout caller repository uses: actions/checkout@v4 - - name: Download export artifacts - uses: actions/download-artifact@v4 + - name: Checkout shared repository (.github) for assemble script + uses: actions/checkout@v4 with: - name: release-export - path: exports + repository: International-Data-Spaces-Association/.github + path: _shared - - name: Merge cover + body PDF (create additional artefact) + - name: Assemble markdown from summary (shared script) + working-directory: ${{ inputs.content_dir }} run: | - python -m pip install --upgrade pip - python -m pip install pypdf - python - <<'PY' - from pypdf import PdfWriter + python3 ../_shared/scripts/assemble_from_summary.py \ + --summary "${{ inputs.summary_path }}" \ + --out "../combined.md" \ + --fail-on-missing - cover = "assets/cover.pdf" - body = "exports/knowledge-base.pdf" - out = "exports/knowledge-base-with-cover.pdf" + - name: Prepare output directory + run: mkdir -p exports - writer = PdfWriter() - writer.append(cover) # cover can be 1 or multiple pages - writer.append(body) - writer.write(out) - print(f"Created {out}") - PY - # pypdf supports merging by appending PDFs via PdfWriter.append() and writing the output. [2](https://bing.com/search?q=material+for+mkdocs+custom+404+page+setup)[3](https://squidfunk.github.io/mkdocs-material/customization/) + - name: Build DOCX (Pandoc in Docker) + uses: docker://${{ inputs.pandoc_image }} + with: + args: >- + combined.md + --from=gfm + --standalone + --resource-path=.:exports:exports/media:docs:docs/external:docs/assets + --output=exports/${{ inputs.output_basename }}.docx - - name: Upload release assets (keep ALL artefacts) - uses: softprops/action-gh-release@v2 + - name: Build PDF (Pandoc + XeLaTeX, KB defaults) + uses: docker://${{ inputs.pandoc_image }} with: - files: | - exports/knowledge-base.pdf - exports/knowledge-base-with-cover.pdf - exports/knowledge-base.docx \ No newline at end of file + args: >- + combined.md + --from=gfm + --standalone + --toc + --number-sections + --pdf-engine=xelatex + -V papersize=${{ inputs.papersize }} + -V geometry:margin=${{ inputs.margin }} + -V fontsize=${{ inputs.fontsize }} + -V mainfont=${{ inputs.mainfont }} + -V sansfont=${{ inputs.sansfont }} + -V monofont=${{ inputs.monofont }} + --resource-path=.:exports:exports/media:docs:docs/external:docs/assets + --output=exports/${{ inputs.output_basename }}.pdf + + - name: Upload export artifacts (PDF + DOCX) + uses: actions/upload-artifact@v4 + with: + name: release-export + path: | + exports/${{ inputs.output_basename }}.pdf + exports/${{ inputs.output_basename }}.docx + if-no-files-found: error \ No newline at end of file