Tips#
Here are some tips about Pelican that you might find useful.
Custom 404 Pages#
When a browser requests a resource that the web server cannot find, the web
server usually displays a generic “File not found” (404) error page that can be
stark and unsightly. One way to provide an error page that matches the theme of
your site is to create a custom 404 page (not an article), such as this
Markdown-formatted example stored in content/pages/404.md
:
Title: Not Found
Status: hidden
Save_as: 404.html
The requested item could not be located. Perhaps you might want to check
the [Archives](/archives.html)?
The next step is to configure your web server to display this custom page
instead of its default 404 page. For Nginx, add the following to your
configuration file’s location
block:
error_page 404 /404.html;
For Apache:
ErrorDocument 404 /404.html
For Amazon S3, first navigate to the Static Site Hosting
menu in the bucket
settings on your AWS console. From there:
Error Document: 404.html
Publishing to GitHub Pages#
If you use GitHub for your Pelican site you can
publish your site to GitHub Pages for free.
Your site will be published to https://<username>.github.io
if it’s a user or
organization site or to https://<username>.github.io/<repository>
if it’s a
project site. It’s also possible to use a custom domain with GitHub Pages.
There are two ways to publish a site to GitHub Pages:
Publishing from a branch: run
pelican
locally and push the output directory to a special branch of your GitHub repo. GitHub will then publish the contents of this branch to your GitHub Pages site.Publishing with a custom GitHub Actions workflow: just push the source files of your Pelican site to your GitHub repo’s default branch and have a custom GitHub Actions workflow run
pelican
for you to generate the output directory and publish it to your GitHub Pages site. This way you don’t need to runpelican
locally. You can even edit your site’s source files using GitHub’s web interface and any changes that you commit will be published.
Publishing a Project Site to GitHub Pages from a Branch#
To publish a Pelican site as a Project Page you need to push the content of
the output
dir generated by Pelican to a repository’s gh-pages
branch
on GitHub.
The excellent ghp-import, which can
be installed with pip
, makes this process really easy.
For example, if the source of your Pelican site is contained in a GitHub repository, and if you want to publish that Pelican site in the form of Project Pages to this repository, you can then use the following:
$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push origin gh-pages
The ghp-import output
command updates the local gh-pages
branch with
the content of the output
directory (creating the branch if it doesn’t
already exist). The git push origin gh-pages
command updates the remote
gh-pages
branch, effectively publishing the Pelican site.
Note
The github
target of the Makefile (and the gh_pages
task of
tasks.py
) created by the pelican-quickstart
command publishes the
Pelican site as Project Pages, as described above.
Publishing a User Site to GitHub Pages from a Branch#
To publish a Pelican site in the form of User Pages, you need to push the
content of the output
dir generated by Pelican to the master
branch of
your <username>.github.io
repository on GitHub.
Again, you can take advantage of ghp-import
:
$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push git@github.com:elemoine/elemoine.github.io.git gh-pages:master
The git push
command pushes the local gh-pages
branch (freshly updated
by the ghp-import
command) to the elemoine.github.io
repository’s
master
branch on GitHub.
Note
To publish your Pelican site as User Pages, feel free to adjust the
github
target of the Makefile.
Another option for publishing to User Pages is to generate the output files in the root directory of the project.
For example, your main project folder is <username>.github.io
and you can
create the Pelican project in a subdirectory called Pelican
. Then from
inside the Pelican
folder you can run:
$ pelican content -o .. -s pelicanconf.py
Now you can push the whole project <username>.github.io
to the master
branch of your GitHub repository:
$ git push origin master
(assuming origin is set to your remote repository).
Publishing to GitHub Pages Using a Custom GitHub Actions Workflow#
Pelican comes with a custom workflow for publishing a Pelican site. To use it:
Enable GitHub Pages in your repo: go to Settings → Pages and choose GitHub Actions for the Source setting.
Commit a
.github/workflows/pelican.yml
file to your repo with these contents:name: Deploy to GitHub Pages on: push: branches: ["main"] workflow_dispatch: jobs: deploy: uses: "getpelican/pelican/.github/workflows/github_pages.yml@master" permissions: contents: "read" pages: "write" id-token: "write" with: settings: "publishconf.py"
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.Once the action completes you should see your Pelican site deployed at your repo’s GitHub Pages URL:
https://<username>.github.io
for a user or organization site orhttps://<username>.github.io/<repository>>
for a project site.
Notes:
You don’t need to set
SITEURL
in your Pelican settings: the workflow will set it for youYou don’t need to commit your
--output
/OUTPUT_PATH
directory (output/
) to git: the workflow will runpelican
to build the output directory for you on GitHub Actions
See GitHub’s docs about reusable workflows 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
file ( |
string |
|
requirements |
No |
The Python requirements to
install, for example to enable
markdown and typogrify use:
|
string |
|
output-path |
No |
Where to output the generated
files ( |
string |
|
For example:
with:
settings: "publishconf.py"
requirements: "pelican[markdown] typogrify"
output-path: "__output__/"
Custom 404 Pages#
GitHub Pages will display the custom 404 page described above, as noted in the relevant GitHub docs.
Update your site on each commit#
To automatically update your Pelican site on each commit, you can create a
post-commit hook. For example, you can add the following to
.git/hooks/post-commit
:
pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages
Copy static files to the root of your site#
To use a custom domain with
GitHub Pages, you need to put the domain of your site (e.g.,
blog.example.com
) inside a CNAME
file at the root of your site. To do
this, create the content/extra/
directory and add a CNAME
file to it.
Then use the STATIC_PATHS
setting to tell Pelican to copy this file to your
output directory. For example:
STATIC_PATHS = ['images', 'extra/CNAME']
EXTRA_PATH_METADATA = {'extra/CNAME': {'path': 'CNAME'},}
Note: use forward slashes, /
, even on Windows.
You can also use the EXTRA_PATH_METADATA
mechanism to place a
favicon.ico
or robots.txt
at the root of any site.
How to add YouTube or Vimeo Videos#
The easiest way is to paste the embed code of the video from these sites directly into your source content.
Alternatively, you can also use Pelican plugins like liquid_tags
,
pelican_youtube
, or pelican_vimeo
to embed videos in your content.
Moreover, markup languages like reST and Markdown have plugins that let you embed videos in the markup. You can use reST video directive for reST or mdx_video plugin for Markdown.
Develop Locally Using SSL#
Here’s how you can set up your local pelican server to support SSL.
First, create a self-signed certificate and key using openssl
(this creates cert.pem
and key.pem
):
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
And use this command to launch the server (the server starts within your output
directory):
python -m pelican.server 8443 --key=../key.pem --cert=../cert.pem
If you are using develop-server.sh
, add this to the top:
CERT="$BASEDIR/cert.pem"
KEY="$BASEDIR/key.pem"
and modify the pelican.server
line as follows:
$PY -m pelican.server $port --ssl --cert="$CERT" --key="$KEY" &