Automatic page publication from Pelican to GitHub Pages
Posté le Sun 21 February 2021 dans pelican
I want to automatically generate and publish the website when I push a modification to the master branch of the GitHub repository.
The tasks.py
script already includes a task to help publishing to gh-pages.
To use it, we need to install invoke
. The gp-pages
task also need the
ghp-import
package.
Finally, while we do not need it for the publication task, the livereload
package
is useful for development, to allow calling invoke livereload
.
Here is my requirements.txt
file, will all those dependencies, and a few others I use for my site:
ghp-import
invoke
livereload
markdown
pelican
typogrify
On GitHub, the master
branch contains the sources of the site, and the gh-pages
branch
contains the published website. There are other ways to do it, for instance by publishing
a subdirectory as the website, but I prefer to work with different branches.
The ghp-import
package makes it easy to manage the gh-pages
branch.
I tweaked a little bit the tasks.py
file. First, I set the name of the branch where to publish:
'github_pages_branch': 'gh-pages',
I also changed some options passed to the ghp-import
script:
@task
def gh_pages(c):
"""Publish to GitHub Pages"""
preview(c)
c.run('ghp-import -n -b {github_pages_branch} '
'-m {commit_message} '
'{deploy_path}'.format(**CONFIG))
I added the -n
option to create the .nojekyll
file. This tells GitHub to not invoke Jekyll
on the generated contents. I removed the -p
option, as I need to include credentials to publish
the pages.
Finally, here is the GitHub Actions configurations:
name: Publish Website
on:
push:
branches: [ master ]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
submodules: true
- name: Set up Python
uses: actions/setup-python@v1
with:
python-version: '3.8'
- name: Install dependencies
run: pip install -r requirements.txt
- name: Build docs
run: invoke gh-pages
- name: Publish docs
run: git push -f "https://${GITHUB_ACTOR}:${{secrets.TOKEN}}@github.com/${GITHUB_REPOSITORY}.git" gh-pages:gh-pages
The action run when I push to master
branch.
The checkout action tells to checkout submodules as well, as I use submodules for the Flex theme, and for pelican-plugins.
I install Python packages from the requirements.txt file.
I call the invoke task to create the (local) gh-pages branch with the published contents.
Finally, I force push the gh-pages branch to GitHub, using the required credentials.