From e46595cdacc57d8a76e8945c7aab5e28686b7f9d Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Tue, 11 Jun 2024 20:03:12 +0100 Subject: [PATCH 1/2] Add theme, Python version, siteurl and feed_domain to GitHub Pages deployment workflow Add theme, Python version, siteurl and feed_domain support to the reusable GitHub Actions workflow for deploying a Pelican site to GitHub Pages: 1. Add a new `theme` option to the workflow that callers can use to specify an external theme to be checked out and used 2. Add a new `python` option to the workflow that callers can use to specify the Python version, in case they need to build their site with a particular version of Python 3. Pass `--extra-settings FEED_DOMAIN='"${{ steps.pages.outputs.base_url }}"'` to the `pelican` command to set the value of Pelican's `FEED_DOMAIN` setting for feed URLs. 4. Add a `feed_domain` input to the workflow so that users can override the feed domain if they need to. 5. Add a `siteurl` input to the workflow so that users can override the site URL if they need to. 6. Add a note to the docs about GitHub Pages generating http:// URLs for https:// sites, and how to fix it 7. Some light editing of the docs for the workflow --- .github/workflows/github_pages.yml | 43 +++++++++++++-- docs/tips.rst | 88 +++++++++++++++++++++--------- 2 files changed, 100 insertions(+), 31 deletions(-) diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml index f4a01b925..efe6959c0 100644 --- a/.github/workflows/github_pages.yml +++ b/.github/workflows/github_pages.yml @@ -17,6 +17,26 @@ on: default: "output/" description: "Where to output the generated files (`pelican`'s `--output` option)" type: string + theme: + required: false + default: "" + description: "The GitHub repo URL of a custom theme to use, for example: 'https://github.com/seanh/sidecar.git'" + type: string + python: + required: false + default: "3.12" + description: "The version of Python to use, for example: '3.12' (to use the most recent version of Python 3.12, this is faster) or '3.12.1' (to use an exact version, slower)" + type: string + siteurl: + required: false + default: "" + description: "The base URL of your web site (Pelican's SITEURL setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases." + type: string + feed_domain: + required: false + default: "" + description: "The domain to be prepended to feed URLs (Pelican's FEED_DOMAIN setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases." + type: string permissions: contents: read pages: write @@ -33,18 +53,31 @@ jobs: - name: Set up Python uses: actions/setup-python@v4 with: - python-version: "3.11" + python-version: ${{ inputs.python }} + - name: Checkout theme + if: ${{ inputs.theme }} + run: git clone '${{ inputs.theme }}' .theme - name: Configure GitHub Pages id: pages uses: actions/configure-pages@v3 - name: Install requirements run: pip install ${{ inputs.requirements }} - name: Build Pelican site + shell: python run: | - pelican \ - --settings "${{ inputs.settings }}" \ - --extra-settings SITEURL='"${{ steps.pages.outputs.base_url }}"' \ - --output "${{ inputs.output-path }}" + import subprocess + + cmd = "pelican" + cmd += " --settings ${{ inputs.settings }}" + cmd += " --extra-settings" + cmd += """ SITEURL='"${{ inputs.siteurl || steps.pages.outputs.base_url }}"'""" + cmd += """ FEED_DOMAIN='"${{ inputs.feed_domain || steps.pages.outputs.base_url }}"'""" + cmd += " --output ${{ inputs.output-path }}" + + if "${{ inputs.theme }}": + cmd += " --theme-path .theme" + + subprocess.run(cmd, shell=True, check=True) - name: Fix permissions run: | chmod -c -R +rX "${{ inputs.output-path }}" | while read line; do diff --git a/docs/tips.rst b/docs/tips.rst index 3344900db..5d75e4fb1 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -163,8 +163,8 @@ Pelican-powered sites can be published to GitHub Pages via a `custom workflow Notes: -* You don't need to set ``SITEURL`` in your Pelican settings: the workflow will - set it for you +* You don't need to set ``SITEURL`` or ``FEED_DOMAIN`` in your Pelican + settings: the workflow will set them correctly 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 @@ -174,36 +174,72 @@ See `GitHub's docs about reusable workflows Date: Mon, 17 Jun 2024 16:38:10 +0100 Subject: [PATCH 2/2] Add Dependabot to GitHub Actions workflow docs --- docs/tips.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/tips.rst b/docs/tips.rst index 5d75e4fb1..338dbe1fa 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -152,6 +152,25 @@ Pelican-powered sites can be published to GitHub Pages via a `custom workflow with: settings: "publishconf.py" + You may want to replace the ``@master`` with the ID of a specific commit in + this repo in order to pin the version of the reusable workflow that you're using: + ``uses: getpelican/pelican/.github/workflows/github_pages.yml@``. + If you do this you might want to get Dependabot to send you automated pull + requests to update that commit ID whenever new versions of this workflow are + published, like so: + + .. code-block:: yaml + + # .github/dependabot.yml + version: 2 + updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "monthly" + + See `GitHub's docs about using Dependabot to keep your actions up to date `_. + 3. Go to the **Actions** tab in your repo (``https://github.com///actions``) and you should see a **Deploy to GitHub Pages** action running.