Best way to publishing to Github Pages annually - using branches?

[pbradl42]

Description

Hello - I have a large project (a factbook) that I want to publish annually. It is currently published to github pages in github-pages branch using quarto publish gh-pages

My question is this: I produce this report annually, and every year there are updates. The old versions of the report must stay accessible and cannot change after publication. I produce PDFs, of course, but I'm looking for the best way to do this with html. I've thought about a couple of options:

1. create an entirely new repo every year (with the year in the title), and publish out to the default gh-pages.
2. create a yearly 'archival' branch from the main repo at the point of publication, and publish that year's book from that branch.

I'd prefer #2, because I don't want a bunch of old repos with more or less the same code sitting around.

BUT, I haven't figured out how to publish to github-pages from a branch. I created a branch for this current year, and I've followed the directions here (https://quarto.org/docs/publishing/github-pages.html) to make that branch the source branch of github-pages branch.

When I try to publish, I get the error that there is already a branch for gh-pages, and I am on the main branch.

Is what I'm envisioning even possible? Should I give up and go with #1?

Is there a better way to do this than branching? Can freezes do what I want?

[mcanouil]

If you need to keep all versions, then you need to publish under a sub-directory.
Look for other discussions about site versioning.

Edit: I've got interrupted, here are the discussions I was referring to:

• First the issue tracking versioned site: Version selector for websites and html books #474
• A discussion about multi-language support which discuss several approaches that could be used in your case Multilingual websites / books #275

[mcanouil]

I haven't figured out how to publish to github-pages from a branch.

quarto publish gh-pages is only there to help users but you don't really need it.
You can deploy from a branch, a directory in a branch, an "environment", and gh-pages (old/legacy approach on GitHub).
These are all well documented on GitHub Docs: https://docs.github.com/en/pages/quickstart.

You Could also write your own GitHub Action workflow, see the very simple examples at https://github.com/quarto-dev/quarto-actions

For example, here is one using the latest deployment workflow from GitHub which does not use branches, it deploys from workflow, so you don't "clutter" your repository: https://github.com/mcanouil/quarto-extensions/blob/main/.github/workflows/deploy.yml

See all publishing method: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site