Contents
Pelican is a static site generator so it generates the html locally and then the site is served up as static HTML without the need for a database or development framework. It's written in Python using Jinja2, Pygments and Docutils.
It has the common blogging features:
There's a good video introduction by Michael Crosby.
Jekyll is the static site generator that gathered the most interest. It's written in Ruby.
Hyde is an reimplementation of Jekyll in Python. I found it hard to identify if it was still an active project or not - though it's very popular.
Blogofile was my first choice but it's been going through a change as the main developer stopped working on it.
Soho is more of a traditional site creation tool, rather than being focused on creating a blog.
Rest2web similar to Soho this tool is focused on creating an entire site rather than a blog so it comes from an earlier generation.
The easiest way to install it is to use virtualenv and Pip. My installation is on Ubuntu 12.04 LTS with Pelican 3.0:
1. Create a virtualenv environment for it:
$ mkproject Pelican (Pelian) $
This creates a virtualenv environment using the virtualenvwrapper commands creating a project directory for you (due to my set-up this is ~/workspace/Pelican) and moving you into it. You know it's been successful because your command prompt now changes to show you that you're in the created virtualenv.
2. Install Pelican itself:
(Pelican) $ pip install pelican # It does a lot of things!
This uses Pip to install Pelican along with any dependencies that it requires. There are quite a few and you can list what's in the system with 'lssitepackages' to get an idea.
3. Create a basic Pelican site:
(Pelican) $ pelican-quickstart
It asks you a bunch of questions to set-up the site for you properly.
To test that HTML generation is working properly use:
(Pelican) $ make html
6. Start the development server You can start the development server and enable it to regenerate content any time it sees any changes with:
(Pelican) $ make devserver
You can now browse to http://127.0.0.1:8000 to see the test content.
Note
You may need to edit develop_server.sh, due to an issue, to add:
PWD="/bin/pwd" BASEDIR=$($PWD)
Having got the basic demonstration site up and running you can configure it to meet your needs.
Inside the source directory there are some files:
There's no templates, themes or extensions folder by default.
These are stored in pelicanconf.py by default. These are the basic settings that come with the system, for more advanced settings see Configuration further down:
AUTHOR = u"Steve George"
SITENAME = u"Futurile"
SITEURL = 'http://www.futurile.net'
# http://pelican.notmyidea.org/en/latest/settings.html#timezone
TIMEZONE = 'UTC'
DEFAULT_LANG = 'en'
# Blogroll
LINKS = ( ('Pelican', 'http;//docs.myidea.org/alexis/pelican/'), ('Python.org', 'http://python.org'), )
# Social widget
SOCIAL = ( ('You can add links here', '#'), )
DEFAULT_PAGINATION = 10
REVERSE_ARCHIVE_ORDER = True
Blog posts and content are written and stored in the 'content' directory by default:
Example blog page ------------------ :title: This is an example title :date: 2010-10-03 10:20 :tags: thats, awesome :category: yeah :author: Alexis Metaireau :excerpt: This is a short description. Here is some content.
If you do not specify a category then Pelican will use the directory structure to work out what the category should be. Equally if you don't specify a date then Pelican will use the files mtime to work out the date for you.
The header itself uses YAML, it is the portion between the -- lines.
The post content can be in either RestructuredText with a file extension of .rst, or in Markdown with a file extension of md.
If you'd like a post to be a draft then you can set this in the metadata, it will then be published to drafts folder:
:status: draft
Note that by default it just puts these into a URL which is the same as the top of the site. So if you create a post with a title of test2 and set the status to draft it will appear as http://mysite.com/test2.html though it will not be linked in the navigation.
If you'd like static pages for the site then you create a directory under your content directory called pages and put the files in there. The content itself can look like a normal RST post.
If you're creating error pages then you can use the metadata to hide them:
:status: hidden
You could use this for a 404 page for example.
Pelican comes with syntax highlighting set-up using Pygments which is one of the dependencies it set-up during install. If you're using RST, then to display a code fragment you use:
.. code-block:: python
print "This is an example code block"
# The code block starts with a blank line and ends with a blank line
You can also over-ride pygments so that you can use your own theme.
There's a default Makefile which you can use to generate the files and put them into the output directory:
(Pelican) $ make html
If you want to clear all the generated files then use:
(Pelican) $ make clean
To serve the output on your machine locally you can use:
(Pelican) $ make serve
This starts a local server which you can browse to on 127.0.0.1:8000
A neat feature is the ability for Pelican to regenerate itself automatically when it sees a change in the content directory. This enables you to make changes and then Pelican will automatically update your running test server without you have to issue the commands. To do this you have to run:
(Pelican) $ make devserver
To stop the running server you can then do:
(Pelican) $ ./develop_server.sh stop
After you've finished writing some content it's time to publish the results. You can use the Makefile as it has a variety of options.
By default there are two configuration files. We edited pelicanconf earlier which we used for our local development. The one for publishing is publishconf.py so you have to edit this to give it similar settings. See the URL settings section for more info.
So, after regenerating the content with the 'production' settings you can then copy the content directory to your host.
I'm using Fabric to publish my content. The short fabfile.py that I have is:
import os
from fabric.api import *
import fabric.contrib.project as project
BASEDIR = os.path.abspath(os.path.curdir)
OUTPUTDIR = os.path.join(BASEDIR, 'sitebuild')
CONFFILE = os.path.join(BASEDIR, 'publishconf.py')
env.hosts=["XXX@myserver.com"]
def build():
""" Build the site for publishing """
local('pelican --output {} --settings {}'.format(OUTPUTDIR, CONFFILE))
def publish():
build()
project.rsync_project(
local_dir="~/workspace/Pelican/sitebuild/",
remote_dir="/users/home/web/public",
exclude=("*_local.py", "*.pyc",)
)
Common configuration settings:
# The default author for pages AUTHOR = u"Steve George" # The default date format expected DEFAULT_DATE_FORMAT = '%d %m %Y' # Show Pages on the main menu bar DISPLAY_PAGES_ON_MENU = True # You have to install rst2pdf for this to work PDF_GENERATOR = True # The name of the site used on the mane page SITE_NAME = u"Futurile" # The name base site URL used in creating feeds: this should be without a trailing slash SITE_URL = 'http://www.futurile.net' # Sets it so that oldests posts are shown first - the default? REVERSE_ARCHIVE_ORDER = True REVERSE_CATEGORY_ORDER = True # The timezone that your working in, taken from http://en.wikipedia.org/wiki/List_of_tz_database_time_zones TIMEZONE = 'Europe/London' THEME = '../blah/theme'
The Pelicanconf.py that we're using lands up looking something like this:
#!/usr/bin/env python
# -*- coding: utf-8 -*- #
AUTHOR = u"Steve George"
SITENAME = u"Futurile"
SITEURL = 'http://www.futurile.net'
TIMEZONE = 'Europe/London'
DEFAULT_LANG = 'en'
DEFAULT_PAGINATION = 10
# Extensions
#TYPOGRIFY = True
#LESS_GENERATOR = True
MENUITEMS = (('About', 'about-me/'),
('Reading', 'reading/'),
('Archive','archives.html'),)
# Blogroll
#LINKS = (('Pelican', 'http://docs.notmyidea.org/alexis/pelican/'), ('Python', 'http://python.org'), ('Jinja2', 'http://jinja.pocoo.org'), ('UKClimbing', 'http://ukclimbing.com'),)
# Social widget
SOCIAL = (('Twitter', 'https://twitter.com/#!futurile') ,)
# Enable pages in the menu
# Set clean urls for pages as well
#DISPLAY_PAGES_ON_MENU = True
PAGE_URL = '{slug}'
PAGE_SAVE_AS = '{slug}/index.html'
#PAGE_URL = '{slug}.html'
#PAGE_SAVE_AS = '{slug}.html'
#PAGE_LANG_URL = '{slug}-{lang}.html'
#PAGE_LANG_SAVE_AS = '{slug}-{lang}.html'
# This sets the location of the pages - creating clean urls
ARTICLE_SAVE_AS = '{date:%Y}/{date:%m}/{date:%d}/{slug}/index.html'
ARTICLE_URL = '{date:%Y}/{date:%m}/{date:%d}/{slug}/'
# Puts the blog articles into reverse order, most recent first - default for blogs
REVERSE_ARTICLE_ORDER = True
# Theme
#THEME = './src/themes/svbtle'
#THEME="pelican-svbtle"
#THEME="notmyidea"
THEME="subtle"
#from pelican.plugins import related_posts
PLUGINS = ['pelican.plugins.related_posts',]
# Tag cloud
# Doesn't seem to do anything
TAG_CLOUD_STEPS = 4
TAG_CLOUD_MAX_ITEMS = 50
# RSS & Atom
#FEED_DOMAIN = SITEURL
#FEED_RSS = 'feeds/rss'
#CATEGORY_FEED_RSS = 'feeds/category/.%s.rss'
#FEED_URL = 'http://feeds.feedburner.com/Futurile'
FEED_DOMAIN = SITEURL
TAG_FEED_RSS = None
#CATEGORY_FEED_ATOM = 'feeds/%s.atom.xml'
FEED_ATOM = 'feeds/all.atom.xml'
# static paths will be copied under the same name
STATIC_PATHS = ["images", ]
# A list of files to copy from the source to the destination
FILES_TO_COPY = ( ('robots.txt', 'robots.txt'), ('images/favicon.ico','favicon.ico'),)
MENUITEMS = ( ('Archives', '{0}/archives.html'.format(SITEURL)), )
###################################################
# Theme specific
####################################################
# Extensions
# GOOGLE_ANALYTICS = 'XXXXXXX'
# DISQUS_SITENAME = 'yourdisqushandle'
# GITHUB_URL = 'http://place-at-github'
# TWITTER_USERNAME = 'username'
By default it copies across the 'images' directory.
This is a set of filters that improve the way in which text is displayed. There's nothing major but it does nice things like stopping titles run over multiple lines when there's just one word on the second line.
If you would like to use less css
First install Less:
(Pelican) $ pip install lesscss
Controlling the URL's that things are actually published too.
The 'slug' bit is a short description in the blog post which describes the post
FIXME: I can't get this to work
For development: ARTICLE_SAVE_AS = '{date:%Y}/{date:%m}/{date:%d}/{slug}/index.html' ARTICLE_URL = '{date:%Y}/{date:%m}/{date:%d}/{slug}/'
For production: #ARTICLE_SAVE_AS = '/{date:%Y}/{date:%m}/{date:%d}/{slug}/index.html' #ARTICLE_URL = '/{date:%Y}/{date:%m}/{date:%d}/{slug}/'
See: http://blog.aclark.net//2012/09/22/sorry-for-the-blog-spam/
There's a themes repository which has most of the common themes in it. There's also a pelican-themes command that you can use the manipulate themes.
Pelican-themes is a command line tool to manage themes in Pelican:
$ pelican-themes --list
Get a theme either through git, or downloading it. This pulls down the pelican themes repository:
$ git clone https://github.com/getpelican/pelican-themes/
Install the theme:
$ pelican-themes --install --verbose /location/of/theme
Removing a theme:
$ pelican-themes --remove <name of theme>
In the future you'll be able to upgrade a theme:
$ pelican-themes --upgrade
This is the default theme that is generated when Pelican creates the initial site, you can see what it looks like on Alex Metaireau's site. It has some specific settings that you can put into the Pelicanconf file:
# Sitename from Disqus DISQUS_SITENAME # Google Analytics page GOOGLE_ANALYTICS = 'XXXXX' # A list of tuples (Title, URL) for additional items to appear in the Menu MENUITEMS LINKS SOCIAL
Pelican-svbtle is a really nice theme when you see it on his site, but I found it a bit difficult to use.
First you need to make a directory to clone the theme into. I'm going to use the pelican-themes app, so the theme itself is installed in Pelican. So I don't need the directory to be in my 'content' location, it can be in the top-level dir of the site:
(Pelican) $ mkdir themes
I clone the git repository:
git clone https://github.com/wting/pelican-svbtle
I install the theme in pelican using:
pelican-themes --install themes/pelican-svbtle/ --verbose
It copies it to Pelican/local/lib/python2.7/sitepackages/pelican/themes/pelican-svbtle
Edit your Pelican configuration file to refer to the pelican-svbtle theme:
THEME = "pelican-svbtle"
I had problems with using it but you get the idea.
To remove it you use:
$ pelican-theme --remove pelican-svbtle
The Subtle theme is really well documented so worth playing around with, it's quite advanced.
Clone the Pelican git repository:
git clone https://github.com/getpelican/pelican-themes
Install the theme as follows:
pelican-themes --install themes/pelican-themes/subtle --verbose
Edit your configuration file to refer to the subtle theme.
Bootlex is an alternative, there's no example of it so I haven't tried it.
Bootstrap 2 is a nice theme. Alex Sulfrian's site uses this theme.
Dev/random focuses on a simple layout and font set-up, an example site is this one.
I'm not sure what the specific differences are between Notmyidea-CMS and the normal Notmyidea.
See this example
Amazium is using responsive design so if you scale the site down to how it would look on a phone it folds everything up for you nicely.
Rach is a really nice theme that Rach Belaid used for his site. It looks completely different, to my eyes, from many of the other Pelican blogs so I like it.
Pelican uses Jinja2 templating engine to output the HTML. Start with the simple theme if you want to create your own theme.
The basic directory structure consists of a static directory and a templates directory. In the statics directory there's a subdirectory for css and a subdirectory for images. Then there is a templates directory which has all the templates that will be used to create the HTML. So structure looks like this:
|--static | |---css | |---images | |---templates |
The mandatory templates in the templates directory are:
archives.html article.html ---> Rendered for any blog post authors.html base.html ---> Rendered for all other templates categories.html category.html index.html ---> Rendered for any index.html page.html tag.html tags.html
The main elements I played with are:
main.css ---> used by the site pygments.css ---> used by pygments for code typogrify.css
Each template receives all the variables that are defined in capitals in the settings file. For example the SITEURL is specified in the conf file so you can access this. Other than that, it's just a matter of going through the templates and playing around with everything.
More information on creating a theme in the documentation, and there's a great Macdrifter post.
In another terminal you have to install a system wide pandoc as it's not covered by Pip:
$ sudo apt-get install pandoc
Install pandoc and BeautifulSoup:
(Pelican) $ lssitepackages # Check to see if BeautifulSoup or pandoc are installed (Pelican) $ pip install BeautifulSoup
Run the pelican-import utility:
$ pelican-import --wpfile futurile.wordpress.xml -o wordpresstest
This outputs all the files to wordpresstest location. You then have to go through them all altering them so that they work correctly!:
$ rst2html --generator --date --strip-comments --verbose --footnote-reference=superscript [inputfile] [outputfile.html]
Then edit the contents by hand to fix any issues.
Other blogs that use Pelican are:
His site bunnyman.info has some good articles and you can see the source of his site on github.
The pydanny site is on gihub, where you can also find the source.
Chipped prism has some nice content.
Has a section on creating a Google sitemap http://www.macdrifter.com/2012/08/pelican-guide-moving-from-wordpress-and-initial-setup.html