Skip to content

Commit e46595c

Browse files
seanhseanh
committed
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
1 parent 5c7e4bb commit e46595c

2 files changed

Lines changed: 100 additions & 31 deletions

File tree

‎.github/workflows/github_pages.yml‎

Lines changed: 38 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,26 @@ on:
1717
default: "output/"
1818
description: "Where to output the generated files (`pelican`'s `--output` option)"
1919
type: string
20+
theme:
21+
required: false
22+
default: ""
23+
description: "The GitHub repo URL of a custom theme to use, for example: 'https://github.com/seanh/sidecar.git'"
24+
type: string
25+
python:
26+
required: false
27+
default: "3.12"
28+
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)"
29+
type: string
30+
siteurl:
31+
required: false
32+
default: ""
33+
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."
34+
type: string
35+
feed_domain:
36+
required: false
37+
default: ""
38+
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."
39+
type: string
2040
permissions:
2141
contents: read
2242
pages: write
@@ -33,18 +53,31 @@ jobs:
3353
- name: Set up Python
3454
uses: actions/setup-python@v4
3555
with:
36-
python-version: "3.11"
56+
python-version: ${{ inputs.python }}
57+
- name: Checkout theme
58+
if: ${{ inputs.theme }}
59+
run: git clone '${{ inputs.theme }}' .theme
3760
- name: Configure GitHub Pages
3861
id: pages
3962
uses: actions/configure-pages@v3
4063
- name: Install requirements
4164
run: pip install ${{ inputs.requirements }}
4265
- name: Build Pelican site
66+
shell: python
4367
run: |
44-
pelican \
45-
--settings "${{ inputs.settings }}" \
46-
--extra-settings SITEURL='"${{ steps.pages.outputs.base_url }}"' \
47-
--output "${{ inputs.output-path }}"
68+
import subprocess
69+
70+
cmd = "pelican"
71+
cmd += " --settings ${{ inputs.settings }}"
72+
cmd += " --extra-settings"
73+
cmd += """ SITEURL='"${{ inputs.siteurl || steps.pages.outputs.base_url }}"'"""
74+
cmd += """ FEED_DOMAIN='"${{ inputs.feed_domain || steps.pages.outputs.base_url }}"'"""
75+
cmd += " --output ${{ inputs.output-path }}"
76+
77+
if "${{ inputs.theme }}":
78+
cmd += " --theme-path .theme"
79+
80+
subprocess.run(cmd, shell=True, check=True)
4881
- name: Fix permissions
4982
run: |
5083
chmod -c -R +rX "${{ inputs.output-path }}" | while read line; do

‎docs/tips.rst‎

Lines changed: 62 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -163,8 +163,8 @@ Pelican-powered sites can be published to GitHub Pages via a `custom workflow
163163

164164
Notes:
165165

166-
* You don't need to set ``SITEURL`` in your Pelican settings: the workflow will
167-
set it for you
166+
* You don't need to set ``SITEURL`` or ``FEED_DOMAIN`` in your Pelican
167+
settings: the workflow will set them correctly for you
168168

169169
* You don't need to commit your ``--output`` / ``OUTPUT_PATH`` directory
170170
(``output/``) to git: the workflow will run ``pelican`` to build the output
@@ -174,36 +174,72 @@ See `GitHub's docs about reusable workflows <https://docs.github.com/en/actions/
174174
for more information.
175175

176176
A number of optional inputs can be added to the ``with:`` block when calling
177-
the workflow:
178-
179-
+--------------+----------+-----------------------------------+--------+---------------+
180-
| Name | Required | Description | Type | Default |
181-
+==============+==========+===================================+========+===============+
182-
| settings | Yes | The path to your Pelican settings | string | |
183-
| | | file (``pelican``'s | | |
184-
| | | ``--settings`` option), | | |
185-
| | | for example: ``"publishconf.py"`` | | |
186-
+--------------+----------+-----------------------------------+--------+---------------+
187-
| requirements | No | The Python requirements to | string | ``"pelican"`` |
188-
| | | install, for example to enable | | |
189-
| | | markdown and typogrify use: | | |
190-
| | | ``"pelican[markdown] typogrify"`` | | |
191-
| | | or if you have a requirements | | |
192-
| | | file: ``"-r requirements.txt"`` | | |
193-
+--------------+----------+-----------------------------------+--------+---------------+
194-
| output-path | No | Where to output the generated | string | ``"output/"`` |
195-
| | | files (``pelican``'s ``--output`` | | |
196-
| | | option) | | |
197-
+--------------+----------+-----------------------------------+--------+---------------+
198-
199-
For example:
177+
the workflow, for example:
200178

201179
.. code-block:: yaml
202180
203181
with:
204182
settings: "publishconf.py"
205183
requirements: "pelican[markdown] typogrify"
206-
output-path: "__output__/"
184+
theme: "https://github.com/seanh/sidecar.git"
185+
python: "3.12"
186+
187+
Here's the complete list of workflow inputs:
188+
189+
+------------------+----------+--------------------------------------------+--------+---------------+
190+
| Name | Required | Description | Type | Default |
191+
+==================+==========+============================================+========+===============+
192+
| ``settings`` | Yes | The path to your Pelican settings | string | |
193+
| | | file (``pelican``'s | | |
194+
| | | ``--settings`` option), | | |
195+
| | | for example: ``"publishconf.py"`` | | |
196+
+------------------+----------+--------------------------------------------+--------+---------------+
197+
| ``requirements`` | No | The Python requirements to | string | ``"pelican"`` |
198+
| | | install, for example to enable | | |
199+
| | | markdown and typogrify use: | | |
200+
| | | ``"pelican[markdown] typogrify"`` | | |
201+
| | | or if you have a requirements | | |
202+
| | | file: ``"-r requirements.txt"`` | | |
203+
+------------------+----------+--------------------------------------------+--------+---------------+
204+
| ``output-path`` | No | Where to output the generated | string | ``"output/"`` |
205+
| | | files (``pelican``'s ``--output`` | | |
206+
| | | option) | | |
207+
+------------------+----------+--------------------------------------------+--------+---------------+
208+
| ``theme`` | No | The GitHub repo URL of a custom | string | ``""`` |
209+
| | | theme to use, for example: | | |
210+
| | | ``"https://github.com/seanh/sidecar.git"`` | | |
211+
+------------------+----------+--------------------------------------------+--------+---------------+
212+
| ``python`` | No | The version of Python to use to build the | string | ``"3.12"`` |
213+
| | | site, for example: ``"3.12"`` (to use the | | |
214+
| | | most recent version of Python 3.12, this | | |
215+
| | | is faster) or ``"3.12.1"`` (to use an | | |
216+
| | | exact version, slower) | | |
217+
+------------------+----------+--------------------------------------------+--------+---------------+
218+
| ``siteurl`` | No | The base URL of your web site (Pelican's | string | The URL of |
219+
| | | ``SITEURL`` setting). If not passed this | | your GitHub |
220+
| | | will default to the URL of your GitHub | | Pages site. |
221+
| | | Pages site, which is correct in most | | |
222+
| | | cases. | | |
223+
+------------------+----------+--------------------------------------------+--------+---------------+
224+
| ``feed_domain`` | | The domain to be prepended to feed URLs | string | The URL of |
225+
| | | (Pelican's ``FEED_DOMAIN`` setting). If | | your GitHub |
226+
| | | not passed this will default to the URL of | | Pages site. |
227+
| | | your GitHub Pages site, which is correct | | |
228+
| | | in most cases. | | |
229+
+------------------+----------+--------------------------------------------+--------+---------------+
230+
231+
232+
"Insecure content" warnings from browsers
233+
"""""""""""""""""""""""""""""""""""""""""
234+
235+
If your site uses ``https://`` and is broken because the browser is blocking
236+
network requests (for example for CSS files) due to "insecure content" this
237+
may be because GitHub Pages is generating ``http://`` URLs for your site.
238+
239+
To fix this go into your site repo's settings and enable the **Enforce HTTPS** setting:
240+
go to **Settings → Pages** and check **Enforce HTTPS**.
241+
Then re-run the workflow to re-deploy your site.
242+
Alternatively, you can use the workflow's ``siteurl`` and ``feed_domain`` settings.
207243

208244
Custom 404 Pages
209245
----------------

0 commit comments

Comments
 (0)