Skip to content

Commit

Permalink
Merge pull request #3330 from seanh/gha-theme-support
Browse files Browse the repository at this point in the history
  • Loading branch information
@justinmayer
justinmayer authored Jun 17, 2024
2 parents 50f77b4 + 135c61f commit b17182e
Show file tree
Hide file tree
Showing 2 changed files with 119 additions and 31 deletions.
43 changes: 38 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,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
Expand All @@ -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
Expand Down
107 changes: 81 additions & 26 deletions docs/tips.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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@<COMMIT_ID>``.
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 <https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot>`_.

3. Go to the **Actions** tab in your repo
(``https://github.com/<username>/<repository>/actions``) and you should see a
**Deploy to GitHub Pages** action running.
Expand All @@ -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
Expand All @@ -174,36 +193,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
----------------
Expand Down

0 comments on commit b17182e

Please sign in to comment.