Playing with Pelican

I spent one day trying to put this blog on Heroku. Googling on the web many authors explain how to create a static site on Heroku, and Pelican web site offer a ready to use buildpack.

Anyway I did not like any of these solutions as all of them seem recompile and install the full stack (nginx, pelican, python....)

I moved to a more pratical and easy to implement solution: GitHub pages and Pelican.

Install Pelican

To install Pelican and other Python package dependencies in a virtual environment, I followed the instructions in the official Pelican documentation.

pip install pelican Markdown typogrify
pelican-quickstart

I enabled article pagination so that I didn't end up with all the posts on a single page. The Makefile is incredibly useful, so I enabled that. It allows you to compile the website with make html and check it live with make serve.

Because I want to use Github pages I answered NO to all the questions about Dropbox, S3, FTP and SSH anyway the related code is still in the Makefile so I removed it manually.

Configure plugins

To configure plugins simply clone pelican-plugins as git submodule with

git add submodule https://github.com/getpelican/pelican-plugins
git submodule update  --init --recursive

and enable what you like in pelicanconf.py

    PLUGIN_PATHS = ['pelican-plugins']
    PLUGINS = ['interlinks',
               'pelican_fontawesome',
               'related_posts',
               'summary',
               'sitemap',
               'simple_footnotes']

Configure Github

For Github you need to put the domain of your site inside a CNAME (must be uppercase) file at the root of your site.

More details how to configure your domain can be found here (Tip #2), here and here

For my configuration I used

content/extras/CNAME

stefanoapostolico.com

pelicanconf.py

    STATIC_PATHS = ['images', 'extras/README.rst', 'extras/CNAME', 
    'extras/robots.txt']

    EXTRA_PATH_METADATA = {
        'extras/README.rst': {'path': 'README.rst'},
        'extras/CNAME': {'path': 'CNAME'},
        'extras/robots.txt': {'path': 'robots.txt'},
    }

Minor improvements

Get metadata from path

To store articles in a structure like category/YEAR/MONTH/DAY-slug so I updated my pelicanconf.py as

   PATH_METADATA = '\A(?P<category>[^/]+)/(?P<date>\d{4}/\d{2}/\d{2})-(?P<slug>.*)(.md|.rst)'

You can always override date, slug and category in your post.

Serve file with different path

To serve your articles with url like /YEAR/MONTH/DAY/slug.html

    ARTICLE_URL = '{date:%Y}/{date:%m}/{date:%d}/{slug}.html'
    ARTICLE_SAVE_AS = '{date:%Y}/{date:%m}/{date:%d}/{slug}.html'

You must set both the setting.

you can see the result here