Add GitHub Actions workflow for GitHub Pages

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 and push the output directory to
a branch.

See: https://github.com/getpelican/pelican/discussions/3174

.github/workflows/github_pages.yml

@@ -0,0 +1,61 @@
+name: Deploy to GitHub Pages
+on:
+  workflow_call:
+    inputs:
+      settings:
+        required: true
+        description: "The path to your Pelican settings file (`pelican`'s `--settings` option), for example: 'publishconf.py'"
+        type: string
+      requirements:
+        required: false
+        default: "pelican"
+        description: "The Python requirements to install, for example to enable markdown and typogrify use: 'pelican[markdown] typogrify'"
+        type: string
+      output-path:
+        required: false
+        default: "output/"
+        description: "Where to output the generated files (`pelican`'s `--output` option)"
+        type: string
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      - name: Configure GitHub Pages
+        id: pages
+        uses: actions/configure-pages@v3
+      - name: Install requirements
+        run: pip install ${{ inputs.requirements }}
+      - name: Build Pelican site
+        run: |
+          pelican \
+            --settings "${{ inputs.settings }}" \
+            --extra-settings SITEURL='"${{ steps.pages.outputs.base_url }}"' \
+            --output "${{ inputs.output-path }}"
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ${{ inputs.output-path }}
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
+

docs/tips.rst

@@ -34,17 +34,30 @@ settings on your AWS console. From there::
 
     Error Document: 404.html
 
-Publishing to GitHub
+Publishing to GitHub Pages
-====================
+==========================
 
-`GitHub Pages <https://help.github.com/categories/20/articles>`_ offer an easy
+If you use `GitHub <https://github.com/>`_ for your Pelican site you can
-and convenient way to publish Pelican sites. There are `two types of GitHub
+publish your site to `GitHub Pages <https://pages.github.com/>`_ for free.
-Pages <https://help.github.com/articles/user-organization-and-project-pages>`_:
+Your site will be published to ``https://<username>.github.io`` if it's a user or
-*Project Pages* and *User Pages*. Pelican sites can be published as both
+organization site or to ``https://<username>.github.io/<repository>`` if it's a
-Project Pages and User Pages.
+project site. It's also possible to `use a custom domain with GitHub Pages <https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site>`_.
 
-Project Pages
+There are `two ways to publish a site to GitHub Pages <https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site>`_:
--------------
+
+1. **Publishing from a branch:** run ``pelican`` locally and push the output
+   directory to a special branch of your GitHub repo. GitHub will then publish
+   the contents of this branch to your GitHub Pages site.
+2. **Publishing with a custom GitHub Actions workflow:** just push the source
+   files of your Pelican site to your GitHub repo's default branch and have a
+   custom GitHub Actions workflow run ``pelican`` for you to generate the
+   output directory and publish it to your GitHub Pages site.  This way you
+   don't need to run ``pelican`` locally. You can even edit your site's source
+   files using GitHub's web interface and any changes that you commit will be
+   published.
+
+Publishing a Project Site to GitHub Pages from a Branch
+-------------------------------------------------------
 
 To publish a Pelican site as a Project Page you need to *push* the content of
 the ``output`` dir generated by Pelican to a repository's ``gh-pages`` branch
@@ -72,8 +85,8 @@ already exist). The ``git push origin gh-pages`` command updates the remote
     ``tasks.py``) created by the ``pelican-quickstart`` command publishes the
     Pelican site as Project Pages, as described above.
 
-User Pages
+Publishing a User Site to GitHub Pages from a Branch
-----------
+----------------------------------------------------
 
 To publish a Pelican site in the form of User Pages, you need to *push* the
 content of the ``output`` dir generated by Pelican to the ``master`` branch of
@@ -110,6 +123,85 @@ branch of your GitHub repository::
 
 (assuming origin is set to your remote repository).
 
+Publishing to GitHub Pages Using a Custom GitHub Actions Workflow
+-----------------------------------------------------------------
+
+Pelican comes with a `custom workflow <https://github.com/getpelican/pelican/blob/master/.github/workflows/github_pages.yml>`_
+for publishing a Pelican site. To use it:
+
+1. Enable GitHub Pages in your repo: go to **Settings → Pages** and choose
+   **GitHub Actions** for the **Source** setting.
+
+2. Commit a ``.github/workflows/pelican.yml`` file to your repo with these contents:
+
+   .. code-block:: yaml
+
+       name: Deploy to GitHub Pages
+       on:
+         push:
+           branches: ["main"]
+         workflow_dispatch:
+       jobs:
+         deploy:
+           uses: "getpelican/pelican/.github/workflows/github_pages.yml@master"
+           permissions:
+             contents: "read"
+             pages: "write"
+             id-token: "write"
+           with:
+             settings: "publishconf.py"
+
+3. Go to the **Actions** tab in your repo
+   (``https://github.com/<username>/<repository>/actions``) and you should see a
+   **Deploy to GitHub Pages** action running.
+
+4. Once the action completes you should see your Pelican site deployed at your
+   repo's GitHub Pages URL: ``https://<username>.github.io`` for a user or
+   organization site or ``https://<username>.github.io/<repository>>`` for a
+   project site.
+
+Notes:
+
+* You don't need to set ``SITEURL`` in your Pelican settings: the workflow will
+  set it for you
+
+* You don't need to commit your ``--output`` / ``OUTPUT_PATH`` directory
+  (``output/``) to git: the workflow will run ``pelican`` to build the output
+  directory for you on GitHub Actions
+
+See `GitHub's docs about reusable workflows <https://docs.github.com/en/actions/using-workflows/reusing-workflows>`_
+for more information.
+
+A number of optional inputs can be added to the ``with:`` block when calling
+the workflow:
+
++--------------+----------+-----------------------------------+--------+---------------+
+| Name         | Required | Description                       | Type   | Default       |
++==============+==========+===================================+========+===============+
+| settings     | Yes      | The path to your Pelican settings | string |               |
+|              |          | file (``pelican``'s               |        |               |
+|              |          | ``--settings`` option),           |        |               |
+|              |          | for example: ``"publishconf.py"`` |        |               |
++--------------+----------+-----------------------------------+--------+---------------+
+| requirements | No       | The Python requirements to        | string | ``"pelican"`` |
+|              |          | install, for example to enable    |        |               |
+|              |          | markdown and typogrify use:       |        |               |
+|              |          | ``"pelican[markdown] typogrify"`` |        |               |
++--------------+----------+-----------------------------------+--------+---------------+
+| output-path  | No       | Where to output the generated     | string | ``"output/"`` |
+|              |          | files (``pelican``'s ``--output`` |        |               |
+|              |          | option)                           |        |               |
++--------------+----------+-----------------------------------+--------+---------------+
+
+For example:
+
+.. code-block:: yaml
+
+    with:
+      settings: "publishconf.py"
+      requirements: "pelican[markdown] typogrify"
+      output-path: "__output__/"
+
 Custom 404 Pages
 ----------------