github/pelican
1
0
Fork 1
mirror of https://github.com/getpelican/pelican.git synced 2025-10-15 20:28:56 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add theme, Python version, siteurl and feed_domain to GitHub Pages deployment workflow

Browse source 
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
This commit is contained in:
Sean Hammond 2024-06-11 20:03:12 +01:00
commit e46595cdac
No known key found for this signature in database
GPG key ID: 17C7DAFDB3DD8A84
2 changed files with 100 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

88
docs/tips.rst
View file

@ -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 <https://docs.github.com/en/actions/
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) | | |
+--------------+----------+-----------------------------------+--------+---------------+
For example:
the workflow, for example:
.. code-block:: yaml
with:
settings: "publishconf.py"
requirements: "pelican[markdown] typogrify"
output-path: "__output__/"
theme: "https://github.com/seanh/sidecar.git"
python: "3.12"
Here's the complete list of workflow inputs:
+------------------+----------+--------------------------------------------+--------+---------------+
| 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) | | |
+------------------+----------+--------------------------------------------+--------+---------------+
| ``siteurl`` | No | The base URL of your web site (Pelican's | string | The URL of |
| | | ``SITEURL`` setting). If not passed this | | your GitHub |
| | | will default to the URL of your GitHub | | Pages site. |
| | | Pages site, which is correct in most | | |
| | | cases. | | |
+------------------+----------+--------------------------------------------+--------+---------------+
| ``feed_domain`` | | The domain to be prepended to feed URLs | string | The URL of |
| | | (Pelican's ``FEED_DOMAIN`` setting). If | | your GitHub |
| | | not passed this will default to the URL of | | Pages site. |
| | | your GitHub Pages site, which is correct | | |
| | | in most cases. | | |
+------------------+----------+--------------------------------------------+--------+---------------+
"Insecure content" warnings from browsers
"""""""""""""""""""""""""""""""""""""""""
If your site uses ``https://`` and is broken because the browser is blocking
network requests (for example for CSS files) due to "insecure content" this
may be because GitHub Pages is generating ``http://`` URLs for your site.
To fix this go into your site repo's settings and enable the **Enforce HTTPS** setting:
go to **Settings → Pages** and check **Enforce HTTPS**.
Then re-run the workflow to re-deploy your site.
Alternatively, you can use the workflow's ``siteurl`` and ``feed_domain`` settings.
Custom 404 Pages
----------------