Include built Quarto site in releases for Zenodo archiving

[maehr]

Describe what feature you'd like. Pseudo-code, mockups, or screenshots of similar solutions are encouraged!

Describe what feature you’d like:

The current GitHub Actions workflow (.github/workflows/quarto‑publish.yml) builds our Quarto project, optimizes the _site directory, and uploads it as an artifact for dead‑link checking and GitHub Pages deployment. However, the generated site is not part of the release archive, so Zenodo only receives the source code. I propose extending the workflow to attach a compressed version of _site to each release. This could be achieved by compressing _site into site.tar.gz, creating a release using actions/create-release, and uploading the archive with actions/upload-release-asset. Example patterns for uploading release assets are provided in community guides. Including the site will ensure that the published DOI captures the fully rendered documentation.

Long description:

The current Quarto publishing workflow builds the _site directory, optimizes it with JamPack, and uploads it as an artifact for the deadlinkcheck job and GitHub Pages deployment. However, the release archive still contains only the source code snapshot; GitHub automatically includes only the code in the tarball/zip. Because the built site is not committed to the repository and is uploaded only as an Actions artifact, it is not packaged into the release and therefore not transferred to Zenodo when a DOI is minted. To remedy this, you need to ensure that the built site (or a compressed version of it) is attached to the release.

Possible solutions

1. Attach the built site as a release asset via GitHub Actions (recommended).

   • After the _site directory is generated in the build-optimize job, compress it into a ZIP or TAR file and store it as an artifact.

   • Create a release in the workflow (e.g., on push of a version tag) using actions/create-release.

   • Use actions/upload-release-asset to upload the compressed site to the release; this requires specifying the upload_url from the release step and the asset_path and asset_name. GitHub’s documentation and examples show that releases can include binary artifacts alongside the source code. Zenodo will archive any files attached to the release, so this ensures the site is preserved.

   • Example snippet (to be adapted for your workflow):

     - name: Compress built site
       run: tar -czf site.tar.gz -C _site .
     - name: Create release
       id: create_release
       uses: actions/create-release@v1
       with:
         tag_name: ${{ github.ref }}
         release_name: ${{ github.ref }}
         draft: false
         prerelease: false
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     - name: Upload built site as release asset
       uses: actions/upload-release-asset@v1
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       with:
         upload_url: ${{ steps.create_release.outputs.upload_url }}
         asset_path: site.tar.gz
         asset_name: site.tar.gz
         asset_content_type: application/gzip
     

   • This approach keeps the repository clean (no committed build artefacts) and ensures the exact site that was deployed is archived with the release.

2. Commit the built site (or a docs/ folder) into the release branch.

   • You can configure Quarto to write output to the docs/ directory and commit that directory to the repository. When you tag a release, the docs/ folder will be included in the source-code tarball.
   • Drawback: the repository size increases over time as built artefacts accumulate. This also clutters diffs and may lead to merge conflicts, so it is generally discouraged for generated content.

3. Use an external tool (e.g., piggyback or the gh CLI) to upload the site to the release manually.

   • Packages like piggyback in R can attach large files to a GitHub release. Similarly, the gh CLI or GitHub’s REST API can be scripted to upload the built site. These tools could be invoked in the workflow after the build step.
   • This adds an extra dependency but functions similarly to the recommended solution.

4. Archive the site separately and reference it in the release metadata.

   • A contrarian option is to treat the static site as a separate data deposit. You can push the built site to Zenodo manually via their API or as a separate repository and then reference its DOI in the main project’s .zenodo.json. This decouples code and site but requires additional curation.

PS: Generated by ChatGPT

What type of pull request would this be?

Enhancement

Any links to similar examples or other references we should review?

No response