I have been on and off keeping a blog well before the term was coined. My
on-line presence started with hand-written HTML using_notepad for
windows 3.0, then HTML 2.0 came out and I start experimenting with
HoTMetaL and HotDog (among the first HTML editors on the market).
Then it came GeoCities, and when I got my fist domain I started using
dynamic sites, using Movable Type at first, then WordPress and
later on Drupal_.
But if there is one thing that all this technological wandering taught me, is
that I seldom if ever use dynamic features on my sites: the only facility
important to me is the possibility to generate feeds and tag pages
automatically. Besides, a dynamic sites means more maintenance, and more
hosting costs.
Go static
So, this time around I started looking for some simple and lean tool, that
would generate static pages that I could push up to some repository server
(like Bitbucket or Github), without having to worry about server
maintenance and security patches. Ever.
Given the rise of GitHub to a prominent actor in this kind of solutions, I
obviously started my quest by looking into Jeckyll and to the very nice
Octopress. No doubt these are very excellent solutions, but - at least
for me - they have two major drawbacks:
- They are based on ruby, which is a language that completely fails to
intrigue me (don’t take this as a judgement on the language in itself,
though: it’s just my personal taste!).
- To leverage the integration with GitHub to its best, you should have the
source of your site available on a GitHub repository (and the free
account on GitHub only allows for public repository).
I would have rather chosen a python-based solution, provided it would have
been actively maintained, and supporting the markdown syntax.
Documentation too had to be extensive and well organised.
Meet Pelican
Lo and behold, after having considered a few alternatives, I settled for
Pelican of which - I must confess - I never heard before.
The pros:
- The underlying technologies are python, markdown and jinja2.
The best of the breed, at least for me.
- Stable, and adopted widely enough to have its little community of
contributors (and themes, and plugins…)
- Very well documented.
- Active: the last commit was days before I started working on this project.
- Flexible organisation of your source files.
- Small but sensible set of feature.
The cons (or at least the few glitches that I have met so far):
- Poor support for Python3 (according to the documentation it should have
worked out-of-the-box, but in reality it did not work at all for me).
- Compulsory use of categories: these are internal to the logic of
Pelican, beside the possibility to use tags. In a perfect world, I would
have very much preferred to have an abstract taxonomy that could represent
both categories and tags.
- Non-intuitive naming convention: for example, the file holding the
configuration used in development is called
pelicanconf.py, while the
one use for producing the “deployable” pages is called publishconf.py.
(I would have considered devel-conf.py and prod-conf.py more apt
names). But also the makefile targets: devserver is the target to start
the server, but stopserver is the one for stopping it.
- Helpers are half-backed and inconsistent. For one, there are a couple
of Makefiles and shell scripts tossed around for no good reason: a python
script would have resulted in much simpler and cleaner code. Besides,
scripts like
pelican-quickstart offers support on certain areas where
one probably would feel safe to do stuff manually (pushing the site live),
but misses out on important ones like installing extra themes or plugins.
- There are very few good themes, and the few that look nice are not responsive.
Configuration
For those interested in trying out a similar setup to mine, here’s a breakdown
of my directory layout:
. (1)
├── content
│ ├── extra (2)
│ ├── images
│ └── pages
├── develop_server.sh
├── Makefile
├── output (3)
├── pelicanconf.py
├── pelicanconf.pyc
├── plugins (4a)
├── publishconf.py
├── publishconf.pyc
└── themes (4b)
(1): This is the main repository (in my case a private repository)(2): Certain files, like robot.txt needs to be copied verbatim every
time the site is generated. I stored such files here and used the
FILES_TO_COPY setting to make pelican aware of it.(3): This is the directory where the static pages are generated. I set
this to be an ignored directory for the main repo at (1) and within it
I cloned my github pages repo (i.e.: the repo, to which I have to push
every time I want to to publish a new version of the site). See below for
more details.(4): Both of these directories are git “submodules”, linked to the themes
and plugins repositories. In other words: these are “sub-repositories”. See
below for more details.
Git magic
It took me a couple of attempts before getting this right, but this is the
key two concept to keep in mind in the above configuration:
- When invoking a git command, git will progressively look “one directory up”
until it will find a valid repository (a
.git directory). So, it is
possible to nest Git repositories and treat them independently, but one
will have to:
- Tell the container repo to ignore the directory where the contained one lives.
- Move to the contained repo every time a command need to be issued for
that specific repository.
Essentially, the two repository will not even be aware of the existence of
the other one.
- Submodules are a different story: the repositories marked as submodules
are known to their container. In fact, commits in the main repository
contain information on what commit is checked out in each submodule.
This is very convenient, as - given a master repository called
foobar,
one can issue g clone --recursive foobar and all submodules will be
checked out correctly, too. You can read more on submodules here.
If you have suggestions for a novice pelican user, you are welcome to leave
them in the comments below! :)