Skip to content

Commit

Permalink
Add theme, Python version and feed domain to GitHub Pages deployment …
Browse files Browse the repository at this point in the history 
…workflow

Add theme, Python version 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.origin }}"'`
   to the `pelican` command to set the value of Pelican's `FEED_DOMAIN`
   setting for feed URLs.
  • Loading branch information
@seanh
seanh committed Jun 17, 2024
1 parent 5c7e4bb commit a3ad621
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 26 deletions.
33 changes: 28 additions & 5 deletions .github/workflows/github_pages.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,16 @@ 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
permissions:
contents: read
pages: write
Expand All @@ -33,18 +43,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='"${{ steps.pages.outputs.base_url }}"'"""
cmd += """ FEED_DOMAIN='"${{ steps.pages.outputs.origin }}"'"""
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
Expand Down
54 changes: 33 additions & 21 deletions docs/tips.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -176,25 +176,35 @@ 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"`` | | |
| | | or if you have a requirements | | |
| | | file: ``"-r requirements.txt"`` | | |
+--------------+----------+-----------------------------------+--------+---------------+
| output-path | No | Where to output the generated | string | ``"output/"`` |
| | | files (``pelican``'s ``--output`` | | |
| | | option) | | |
+--------------+----------+-----------------------------------+--------+---------------+
+--------------+----------+--------------------------------------------+--------+---------------+
| 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"`` | | |
| | | or if you have a requirements | | |
| | | file: ``"-r requirements.txt"`` | | |
+--------------+----------+--------------------------------------------+--------+---------------+
| output-path | No | Where to output the generated | string | ``"output/"`` |
| | | files (``pelican``'s ``--output`` | | |
| | | option) | | |
+--------------+----------+--------------------------------------------+--------+---------------+
| theme | No | The GitHub repo URL of a custom | string | ``""`` |
| | | theme to use, for example: | | |
| | | ``"https://github.com/seanh/sidecar.git"`` | | |
+--------------+----------+--------------------------------------------+--------+---------------+
| python | No | The version of Python to use to build the | string | ``"3.12"`` |
| | | site, 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) | | |
+--------------+----------+--------------------------------------------+--------+---------------+

For example:

Expand All @@ -204,6 +214,8 @@ For example:
settings: "publishconf.py"
requirements: "pelican[markdown] typogrify"
output-path: "__output__/"
theme: "https://github.com/seanh/sidecar.git"
python: "3.12"
Custom 404 Pages
----------------
Expand Down

0 comments on commit a3ad621

Please sign in to comment.