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..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. @@ -163,8 +182,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 +193,72 @@ See `GitHub's docs about reusable workflows