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 cosole. From there:

Error Document: 404.html

Publishing to GitHub

GitHub Pages offer an easy and convenient way to publish Pelican sites. There are two types of GitHub Pages: Project Pages and User Pages. Pelican sites can be published as both Project Pages and User Pages.

Project Pages

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
$ 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 the Fabfile) created by the pelican-quickstart command publishes the Pelican site as Project Pages, as described above.

Note

ghp-import on Windows

Until ghp-import Pull Request #25 is accepted, you will need to install a custom build of ghp-import: pip install https://github.com/chevah/ghp-import/archive/win-support.zip

User Pages

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

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.