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

Merge pull request #3330 from seanh/gha-theme-support

Browse source
This commit is contained in:
Justin Mayer 2024-06-17 20:43:09 +02:00 • committed by GitHub
commit b17182ece1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 119 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

43
.github/workflows/github_pages.yml vendored
View file

@ -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

107
docs/tips.rst
View file

@ -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.
@ -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 <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
----------------