Add GitHub Actions workflow for GitHub Pages

[seanh]

Add a GitHub Actions workflow that users can use to publish their Pelican sites to GitHub Pages by running pelican on GitHub Actions, without having to run pelican locally or push the output directory to a branch. See: #3174 for some discussion.

[seanh]

GitHub themselves provide starter workflows for publishing to GitHub Pages using various static site generators (unfortunately not including Pelican), the way I've designed this workflow is similar to these: https://github.com/actions/starter-workflows/tree/main/pages

[avaris]

I'm not sure how I feel about hosting a workflow file under .github/workflows that is not used in this repository, just to make it reusable. I'm just saying this before I start reviewing, which will have to wait for some free time for me.

[seanh]

Reusable workflows have to be under .github/workflows/ otherwise GitHub won't recognise them. Unfortunately they can't be in a subdirectory of .github/workflows/ either (docs).

It could be moved into a .github/workflows/ directory of a separate getpelican/workflows repo, but the nice thing about having the workflow be in the getpelican/pelican repo itself is that you can change the workflow and its associated documentation at the same time, in one PR. So we might want to move the workflow's documentation into the README.md of the new workflows repo as well.

[lioman]

I'm not sure how I feel about hosting a workflow file under .github/workflows that is not used in this repository, just to make it reusable. I'm just saying this before I start reviewing, which will have to wait for some free time for me.

That is a valid point. On the other side, I think it would be good to have (even if I don't use it). Many projects on GH just use a different approach: They create a dedicated repo for that action in same org.
One could do the same and have the minimal documentation as a pelican site deployed as github page from that said repo.
Benefits:

• this repo is not cluttered with unused code
• the action is tested and used with it's own documentation

Con:

• another repo to maintain

[seanh]

When I have a bit more time I can update my demo site to use the github_pages.yml workflow from this branch, so that'll work as a test/demo of this PR (the demo site currently uses the one from my https://github.com/seanh/pelican-github-pages repo)

[seanh]

@avaris I've done a bit more work on this and it's ready for review now:

• Removed the caching stuff from this PR since it's a bit of a tricky problem in its own right. If desired I can send a follow-up PR to add caching so we can discuss and accept or reject it separately
• Added a requirements input to the workflow to enable users to install things like markdown, typogrify and plugins
• Added settings and output-path inputs to the workflow, corresponding to pelican's --settings and --output options
• Tidied up the docs by using a table to document all the workflow inputs at once

I've also changed https://github.com/seanh/pelican-github-pages-demo/ to use the workflow from this PR, so see that repo for a working example

[avaris]

Thanks @seanh, I will certainly take a look when my schedule permits, but it's very unlikely for the next couple weeks :(.

[seanh]

Hey, no worries 👍

[avaris]

I added the additional documentation. Good to merge, thanks!

[justinmayer]

Many thanks to @seanh for the contribution and to @avaris for reviewing and documenting.