What is Pelican?
Pelican is a static site generator. It's written in Python, focusing on blogs, using reStructuredText, Jinja2 and Fabric (but you can use Markdown and makefiles and has provisions for normal web pages as well). It's a pythonic tool that's easy to use and was a breeze to setup.
Installing Pelican
As Pelican is a static blog/ website generator, all we're doing is in your workstation. All you need to have server-wise is a bog-standard web server (like Apache or Nginx). Everything else is done on your local machine. I installed Pelican from Debian (it's currently available in testing)
apt-get install python-pelican fabric
Alternatively, you can use pip
pip install pelican fabric
Creating a blog
Create a blog directory and an empty blog
$ mkdir blog $ cd blog $ pelican-quickstart Welcome to pelican-quickstart v3.4.0. This script will help you create a new Pelican-based website. Please answer the following questions so this script can generate the files needed by Pelican. > Where do you want to create your new web site? [.] > What will be the title of this web site? My Blog > Who will be the author of this web site? <Insert you name here> > What will be the default language of this web site? [en] > Do you want to specify a URL prefix? e.g., http://example.com (Y/n) > What is your URL prefix? (see above example; no trailing slash) <Insert blog URL without trailing slash> > Do you want to enable article pagination? (Y/n) > How many articles per page do you want? [10] > Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) > Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) > Do you want to upload your website using FTP? (y/N) > Do you want to upload your website using SSH? (y/N) y > What is the hostname of your SSH server? [localhost] <Insert SSH server address> > What is the port of your SSH server? [22] > What is your username on that server? [root] <Insert SSH username> > Where do you want to put your web site on that server? [/var/www] <Insert full path to your blog's directory> > Do you want to upload your website using Dropbox? (y/N) > Do you want to upload your website using S3? (y/N) > Do you want to upload your website using Rackspace Cloud Files? (y/N) > Do you want to upload your website using GitHub Pages? (y/N) Done. Your new project is available at blog
Since Pelican uses OpenSSH, you can use servers defined in your SSH preferences. Now, lets configure the blog to our liking.
Configuration
In the blog directory there are the 2 configuration files: pelicanconf.py for configuring Pelican and publishconf.py for configuration that are only for publishing using Make or Fabric. Pelican also creates standard Makefile and fabfile.py for you. I've made the following modifications to pelicanconf.py:
TIMEZONE = 'Asia/Jerusalem'
PATH = "content"
DIRECT_TEMPLATES = ('index', 'archives')
DISPLAY_CATEGORIES_ON_MENU = False
DISPLAY_PAGES_ON_MENU = True
TAGS_SAVE_AS = ''
TAG_SAVE_AS = ''
STATIC_PATH = ['static']
And to publishconf.py:
CATEGORY_FEED_ATOM = None
I've set the timezone to mine (so that the time of published articles is correct), add everything under contents/static as static contents to be uploaded to the server, disabled showing of categories of articles and creating feeds for them, disabled saving of articles by tags and set pages (which are simple web pages unlike articles which are blog entries) to show on the menu. Next, themes.
Themes
Pelican comes with a default theme (the same as used by Pelican's website) but I wanted something more understated so I took at look at https://github.com/getpelican/pelican-themes and chose pelican-mockingbird. Either clone it or add it as a git submodule (depends on if you're using Git to version control your blog or not)
git clone https://github.com/wrl/pelican-mockingbird.git #If you're not using Git. git submodule add https://github.com/wrl/pelican-mockingbird.git #If you're using Git.
and set the theme to that by adding the following to pelicanconf.py:
THEME = "./pelican-mockingbird"
I've also edited base.html and article.html inside of pelican-mockingbird/templates to suite my liking. Next, let us add a new entry.
Adding an entry
Create a ReStructuredText file inside of contents. The filename is for personal use and not critical. The heading is the article name and you can add the following for Pelican to use:
:date: 2014-04-19 :slug: this-will-the-filename :author: <Insert your name here> :summary: <Insert summary here>
After we added the content we want to upload it to our web server (I use fabric)
fab publish
If you don't have keys set for the server it will ask you for your password to the server. Last thing, you can create pages, create a pages directory inside contents and save the files there. Their format is the same as articles but they'll have a somewhat template applied and they will be shown in the menu. A good example will an 'About Me' page.
That's it, you now have Pelican installed, configured and published to your web site. If you want to see a real life example, clone my blog.