Getting started

Installing

You’re ready? Let’s go ! You can install pelican in a lot of different ways, the simpler one is via pip:

$ pip install pelican

If you have the sources, you can install pelican using the distutils command install. I recommend to do so in a virtualenv:

$ virtualenv .
$ source bin/activate
$ python setup.py install

Dependencies

At this time, pelican is dependent of the following python packages:

  • feedgenerator, to generate the ATOM feeds.
  • jinja2, for templating support.

If you’re not using python 2.7, you will also need argparse.

Optionally:

  • docutils, for reST support
  • pygments, to have syntactic colorization with resT input
  • Markdown, for Markdown as an input format

Writing articles using pelican

Files metadata

Pelican tries to be smart enough to get the informations it needs from the file system (for instance, about the category of your articles), but you need to provide by hand some of those informations in your files.

You could provide the metadata in the restructured text files, using the following syntax (give your file the .rst extension):

My super title
##############

:date: 2010-10-03 10:20
:tags: thats, awesome
:category: yeah
:author: Alexis Metaireau

You can also use a markdown syntax (with a file ending in .md):

Date: 2010-12-03
Title: My super title

Put you content here.

Note that none of those are mandatory: if the date is not specified, pelican will rely on the mtime of your file, and the category can also be determined by the directory where the rst file is. For instance, the category of python/foobar/myfoobar.rst is foobar.

Generate your blog

To launch pelican, just use the pelican command:

$ pelican /path/to/your/content/ [-s path/to/your/settings.py]

And… that’s all! You can see your weblog generated on the content/ folder.

This one will just generate a simple output, with the default theme. It’s not really sexy, as it’s a simple HTML output (without any style).

You can create your own style if you want, have a look to the help to see all the options you can use:

$ pelican --help

Pages

If you create a folder named pages, all the files in it will be used to generate static pages.

Then, use the DISPLAY_PAGES_ON_MENU setting, which will add all the pages to the menu.

Importing an existing blog

It is possible to import wordpress themes and RSS themes using a script which is living in tools: importer.

You can call it this way for a wordpress import:

$ python importer.py --wpfile /your/wordpress/export -o output_dir

And like this for an import from an RSS feed:

$ python importer.py --feed http://your/rss/feed -o output_dir

Translations

It is possible to translate articles. To do so, you need to add a lang meta in your articles/pages, and to set a DEFAULT_LANG setting (which is en by default). Then, only articles with this default language will be listed, and each article will have a translation list.

Pelican uses the “slug” of two articles to compare if they are translations of each others. So it’s possible to define (in restructured text) the slug directly.

Here is an exemple of two articles (one in english and the other one in french).

The english one:

Foobar is not dead
##################

:slug: foobar-is-not-dead
:lang: en

That's true, foobar is still alive !

And the french one:

Foobar n'est pas mort !
#######################

:slug: foobar-is-not-dead
:lang: fr

Oui oui, foobar est toujours vivant !

Despite the text quality, you can see that only the slug is the same here. You’re not forced to define the slug that way, and it’s completely possible to have two translations with the same title (which defines the slug)

Syntactic recognition

Pelican is able to regognise the syntax you are using, and to colorize the right way your block codes. To do so, you have to use the following syntax:

.. code-block:: identifier

   your code goes here

The identifier is one of the lexers available here.

Autoreload

It’s possible to tell pelican to watch for your modifications, instead of manually launching it each time you need. Use the -r option, or –autoreload.

Publishing drafts

If you want to publish an article as a draft, for friends to review it for instance, you can add a status: draft to its metadata, it will then be available under the drafts folder, and not be listed under the index page nor any category page.

Fork me on GitHub