PK †½tA¿.î‚ ‚ pelican-3.0/genindex.html
This section describe how Pelican works internally. As you’ll see, it’s quite simple, but a bit of documentation doesn’t hurt. :)
You can also find in the Some history about Pelican section an excerpt of a report the original author wrote with some software design information.
What Pelican does is take a list of files and process them into some sort of output. Usually, the input files are reStructuredText and Markdown files, and the output is a blog, but both input and output can be anything you want.
The logic is separated into different classes and concepts:
Is there an awesome markup language you want to add to Pelican? Well, the only thing you have to do is to create a class with a read method that returns HTML content and some metadata.
Take a look at the Markdown reader:
class MarkdownReader(Reader):
enabled = bool(Markdown)
def read(self, filename):
"""Parse content and metadata of markdown files"""
text = open(filename)
md = Markdown(extensions = ['meta', 'codehilite'])
content = md.convert(text)
metadata = {}
for name, value in md.Meta.items():
if name in _METADATA_FIELDS:
meta = _METADATA_FIELDS[name](value[0])
else:
meta = value[0]
metadata[name.lower()] = meta
return content, metadata
Simple, isn’t it?
If your new reader requires additional Python dependencies, then you should wrap their import statements in a try...except block. Then inside the reader’s class, set the enabled class attribute to mark import success or failure. This makes it possible for users to continue using their favourite markup method without needing to install modules for formats they don’t use.
Generators have two important methods. You’re not forced to create both; only the existing ones will be called.
pelican-themes is a command line tool for managing themes for Pelican.
-h, --help | Show the help an exit |
-l, --list | Show the themes already installed |
-i theme_path, --install theme_path | |
One or more themes to install | |
-r theme_name, --remove theme_name | |
One or more themes to remove | |
-s theme_path, --symlink theme_path | |
Same as “–install”, but create a symbolic link instead of copying the theme. Useful for theme development | |
-v, --verbose | Verbose output |
--version | Print the version of this script |
With pelican-themes, you can see the available themes by using the -l or --list option:
$ pelican-themes -l
notmyidea
two-column@
simple
$ pelican-themes --list
notmyidea
two-column@
simple
In this example, we can see there are three themes available: notmyidea, simple, and two-column.
two-column is prefixed with an @ because this theme is not copied to the Pelican theme path, but is instead just linked to it (see Creating symbolic links for details about creating symbolic links).
Note that you can combine the --list option with the -v or --verbose option to get more verbose output, like this:
$ pelican-themes -v -l
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/notmyidea
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/two-column (symbolic link to `/home/skami/Dev/Python/pelican-themes/two-column')
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/simple
You can install one or more themes using the -i or --install option. This option takes as argument the path(s) of the theme(s) you want to install, and can be combined with the verbose option:
# pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms --verbose
# pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms\
~/Dev/Python/pelican-themes/martyalchin \
--verbose
# pelican-themes -vi ~/Dev/Python/pelican-themes/two-column
The pelican-themes command can also remove themes from the Pelican themes path. The -r or --remove option takes as argument the name(s) of the theme(s) you want to remove, and can be combined with the --verbose option.
# pelican-themes --remove two-column
# pelican-themes -r martyachin notmyidea-cmd -v
pelican-themes can also install themes by creating symbolic links instead of copying entire themes into the Pelican themes path.
To symbolically link a theme, you can use the -s or --symlink, which works exactly as the --install option:
# pelican-themes --symlink ~/Dev/Python/pelican-themes/two-column
In this example, the two-column theme is now symbolically linked to the Pelican themes path, so we can use it, but we can also modify it without having to reinstall it after each modification.
This is useful for theme development:
$ sudo pelican-themes -s ~/Dev/Python/pelican-themes/two-column
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ firefox /tmp/out/index.html
$ vim ~/Dev/Pelican/pelican-themes/two-coumn/static/css/main.css
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ cp /tmp/bg.png ~/Dev/Pelican/pelican-themes/two-coumn/static/img/bg.png
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ vim ~/Dev/Pelican/pelican-themes/two-coumn/templates/index.html
$ pelican ~/Blog/content -o /tmp/out -t two-column
The --install, --remove and --symlink option are not mutually exclusive, so you can combine them in the same command line to do more than one operation at time, like this:
# pelican-themes --remove notmyidea-cms two-column \
--install ~/Dev/Python/pelican-themes/notmyidea-cms-fr \
--symlink ~/Dev/Python/pelican-themes/two-column \
--verbose
In this example, the theme notmyidea-cms is replaced by the theme notmyidea-cms-fr
You’re ready? Let’s go! You can install Pelican via several different methods. The simplest is via pip:
$ pip install pelican
If you don’t have pip installed, an alternative method is easy_install:
$ easy_install pelican
While the above is the simplest method, the recommended approach is to create a virtual environment for Pelican via virtualenv and virtualenvwrapper before installing Pelican. Assuming you’ve followed the virtualenvwrapper installation and shell configuration steps, you can then open a new terminal session and create a new virtual environment for Pelican:
$ mkvirtualenv pelican
Once the virtual environment has been created and activated, Pelican can be be installed via pip or easy_install as noted above. Alternatively, if you have the project source, you can install Pelican using the distutils method:
$ cd path-to-Pelican-source
$ python setup.py install
If you have Git installed and prefer to install the latest bleeding-edge version of Pelican rather than a stable release, use the following command:
$ pip install -e git://github.com/getpelican/pelican#egg=pelican
If you plan on using Markdown as a markup format, you’ll need to install the Markdown library as well:
$ pip install Markdown
If you installed a stable Pelican release via pip or easy_install and wish to upgrade to the latest stable release, you can do so by adding --upgrade to the relevant command. For pip, that would be:
$ pip install --upgrade pelican
If you installed Pelican via distutils or the bleeding-edge method, simply perform the same step to install the most recent version.
At this time, Pelican is dependent on the following Python packages:
If you’re not using Python 2.7, you will also need the argparse package.
Optionally:
Following is a brief tutorial for those who want to get started right away. We’re going to assume that virtualenv and virtualenvwrapper are installed and configured; if you’ve installed Pelican outside of a virtual environment, you can skip to the pelican-quickstart command. Let’s first create a new virtual environment and install Pelican into it:
$ mkvirtualenv pelican
$ pip install pelican Markdown
Next we’ll create a directory to house our site content and configuration files, which can be located any place you prefer, and associate this new project with the currently-active virtual environment:
$ mkdir ~/code/yoursitename
$ cd ~/code/yoursitename
$ setvirtualenvproject
Now we can run the pelican-quickstart command, which will ask some questions about your site:
$ pelican-quickstart
Once you finish answering all the questions, you can begin adding content to the content folder that has been created for you. (See Writing articles using Pelican section below for more information about how to format your content.) Once you have some content to generate, you can convert it to HTML via the following command:
$ make html
If you’d prefer to have Pelican automatically regenerate your site every time a change is detected (handy when testing locally), use the following command instead:
$ make regenerate
To serve the site so it can be previewed in your browser at http://localhost:8000:
$ make serve
Normally you would need to run make regenerate and make serve in two separate terminal sessions, but you can run both at once via:
$ make devserver
The above command will simultaneously run Pelican in regeneration mode as well as serve the output at http://localhost:8000. Once you are done testing your changes, you should stop the development server via:
$ ./develop_server.sh stop
When you’re ready to publish your site, you can upload it via the method(s) you chose during the pelican-quickstart questionnaire. For this example, we’ll use rsync over ssh:
$ make rsync_upload
That’s it! Your site should now be live.
Pelican tries to be smart enough to get the information it needs from the file system (for instance, about the category of your articles), but some information you need to provide in the form of metadata inside your files.
You can provide this metadata in reStructuredText text files via 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
Pelican implements an extension of reStructuredText to enable support for the abbr HTML tag. To use it, write something like this in your post:
This will be turned into :abbr:`HTML (HyperText Markup Language)`.
You can also use Markdown syntax (with a file ending in .md). Markdown generation will not work until you explicitly install the Markdown package, which can be done via pip install Markdown. Metadata syntax for Markdown posts should follow this pattern:
Date: 2010-12-03
Title: My super title
Tags: thats, awesome
Slug: my-super-post
This is the content of my super blog post.
Note that, aside from the title, none of this metadata is mandatory: if the date is not specified, Pelican will rely on the file’s “mtime” timestamp, and the category can be determined by the directory in which the file resides. For example, a file located at python/foobar/myfoobar.rst will have a category of foobar.
The make shortcut commands mentioned in the Kickstart a blog section are mostly wrappers around the pelican command that generates the HTML from the content. The pelican command can also be run directly:
$ pelican /path/to/your/content/ [-s path/to/your/settings.py]
The above command will generate your weblog and save it in the content/ folder, using the default theme to produce a simple site. The default theme is simple HTML without styling and is provided so folks may use it as a basis for creating their own themes.
Pelican has other command-line switches available. Have a look at the help to see all the options you can use:
$ pelican --help
It’s possible to tell Pelican to watch for your modifications, instead of manually re-running it every time you want to see your changes. To enable this, run the pelican command with the -r or --autoreload option.
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.
If you want to exclude any pages from being linked to or listed in the menu then add a status: hidden attribute to its metadata. This is useful for things like making error pages that fit the generated theme of your site.
It is possible to import your blog from Dotclear, WordPress, and RSS feeds using a simple script. See Import from other blog software.
It is possible to translate articles. To do so, you need to add a lang meta attribute to your articles/pages and set a DEFAULT_LANG setting (which is English [en] by default). With those settings in place, only articles with the default language will be listed, and each article will be accompanied by a list of available translations for that article.
Pelican uses the article’s URL “slug” to determine if two or more articles are translations of one another. The slug can be set manually in the file’s metadata; if not set explicitly, Pelican will auto-generate the slug from the title of the article.
Here is an example of two articles, one in English and the other in French.
The English article:
Foobar is not dead
##################
:slug: foobar-is-not-dead
:lang: en
That's true, foobar is still alive!
And the French version:
Foobar n'est pas mort !
#######################
:slug: foobar-is-not-dead
:lang: fr
Oui oui, foobar est toujours vivant !
Post content quality notwithstanding, you can see that only item in common between the two articles is the slug, which is functioning here as an identifier. If you’d rather not explicitly define the slug this way, you must then instead ensure that the translated article titles are identical, since the slug will be auto-generated from the article title.
Pelican is able to provide colorized syntax highlighting for your code blocks. To do so, you have to use the following conventions (you need to put this in your content files).
For RestructuredText:
.. code-block:: identifier
your code goes here
For Markdown, format your code blocks thusly:
:::identifier
your code goes here
The specified identifier should be one that appears on the list of available lexers.
If you want to publish an article as a draft (for friends to review before publishing, for example), you can add a status: draft attribute to its metadata. That article will then be output to the drafts folder and not listed on the index page nor on any category page.
The files generated by Pelican are static files, so you don’t actually need anything special to see what’s happening with the generated files.
You can either use your browser to open the files on your disk:
$ firefox output/index.html
Or run a simple web server using Python:
cd output && python -m SimpleHTTPServer
Warning
This page comes from a report the original author (Alexis Métaireau) wrote right after writing Pelican, in December 2010. The information may not be up-to-date.
Pelican is a simple static blog generator. It parses markup files (Markdown or reStructuredText for now) and generates an HTML folder with all the files in it. I’ve chosen to use Python to implement Pelican because it seemed to be simple and to fit to my needs. I did not wanted to define a class for each thing, but still wanted to keep my things loosely coupled. It turns out that it was exactly what I wanted. From time to time, thanks to the feedback of some users, it took me a very few time to provide fixes on it. So far, I’ve re-factored the Pelican code by two times; each time took less than 30 minutes.
I was previously using WordPress, a solution you can host on a web server to manage your blog. Most of the time, I prefer using markup languages such as Markdown or reStructuredText to type my articles. To do so, I use vim. I think it is important to let the people choose the tool they want to write the articles. In my opinion, a blog manager should just allow you to take any kind of input and transform it to a weblog. That’s what Pelican does. You can write your articles using the tool you want, and the markup language you want, and then generate a static HTML weblog.
To be flexible enough, Pelican has template support, so you can easily write your own themes if you want to.
Pelican came from a need I have. I started by creating a single file application, and I have make it grow to support what it does by now. To start, I wrote a piece of documentation about what I wanted to do. Then, I created the content I wanted to parse (the reStructuredText files) and started experimenting with the code. Pelican was 200 lines long and contained almost ten functions and one class when it was first usable.
I have been facing different problems all over the time and wanted to add features to Pelican while using it. The first change I have done was to add the support of a settings file. It is possible to pass the options to the command line, but can be tedious if there is a lot of them. In the same way, I have added the support of different things over time: Atom feeds, multiple themes, multiple markup support, etc. At some point, it appears that the “only one file” mantra was not good enough for Pelican, so I decided to rework a bit all that, and split this in multiple different files.
I’ve separated the logic in different classes and concepts:
I also deal with contents objects. They can be Articles, Pages, Quotes, or whatever you want. They are defined in the contents.py module and represent some content to be used by the program.
Here is an overview of the classes involved in Pelican.
The interface does not really exist, and I have added it only to clarify the whole picture. I do use duck typing and not interfaces.
Internally, the following process is followed:
I make two calls because it is important that when the output is generated by the generators, the context will not change. In other words, the first method generate_context should modify the context, whereas the second generate_output method should not.
Then, it is up to the generators to do what the want, in the generate_context and generate_content method. Taking the ArticlesGenerator class will help to understand some others concepts. Here is what happens when calling the generate_context method:
Then, the generate_content method uses the context and the writer to generate the wanted output.
Pelican is a static site generator, written in Python.
Pelican currently supports:
“Pelican” is an anagram for calepin, which means “notebook” in French. ;)
You can access the source code at: https://github.com/getpelican/pelican
If you want to see new features in Pelican, don’t hesitate to offer suggestions, clone the repository, etc. There are many ways to contribute. That’s open source, dude!
Send a message to “alexis at notmyidea dot org” with any requests/feedback! You can also join the team at #pelican on Freenode (or if you don’t have an IRC client handy, use the webchat for quick feedback.
A French version of the documentation is available at Pelican.
Here is a summary of the frequently asked questions for Pelican.
If you have a problem, question, or suggestion, please start by striking up a conversation on #pelican on Freenode. Those who don’t have an IRC client handy can jump in immediately via IRC webchat. Because of differing time zones, you may not get an immediate response to your question, but please be patient and stay logged into IRC — someone will almost always respond.
If you are unable to resolve your issue or if you have a feature request, please refer to the issue tracker.
There are several ways to help out. First, you can use Pelican and report any suggestions or problems you might have via IRC or the issue tracker.
If you want to contribute, please fork the git repository, create a new feature branch, make your changes, and issue a pull request. Someone will review your changes as soon as possible. Please refer to the How to Contribute section for more details.
You can also contribute by creating themes and improving the documentation.
No, it’s not. Configuration files are just an easy way to configure Pelican. For basic operations, it’s possible to specify options while invoking Pelican via the command line. See pelican --help for more information.
Pygments adds some classes to the generated content. These classes are used by themes to style code syntax highlighting via CSS. Specifically, you can customize the appearance of your syntax highlighting via the .codehilite pre class in your theme’s CSS file. To see how various styles can be used to render Django code, for example, you can use the demo on the project website.
Please refer to How to create themes for Pelican.
Markdown is not a hard dependency for Pelican, so you will need to explicitly install it. You can do so by typing:
$ (sudo) pip install markdown
In case you don’t have pip installed, consider installing it via:
$ (sudo) easy_install pip
Yes. For example, to include a modified date in a Markdown post, one could include the following at the top of the article:
Modified: 2012-08-08
That meta-data can then be accessed in the template:
{% if article.modified %}
Last modified: {{ article.modified}}
{% endif %}
It’s as simple as adding an extra line of metadata to any pages or articles you want to have its own template.
template: template_name
Then just make sure to have the template installed in to your theme as template_name.html.
To disable all feed generation set FEED_ATOM and FEED_RSS to None in your settings. Please note None and '' are not the same thing. The word None should not be surrounded by quotes.
RSS and Atom feeds require all URLs and links in them to be absolute. In order to properly generate all URLs properly in Pelican you will need to set SITEURL to the full path of your blog. When using make html and the default Makefile provided by the pelican-quickstart bootstrap script to test build your site, it’s normal to see this warning since SITEURL is deliberately left undefined. If configured properly no other make commands should result in this warning.
Feeds are still generated when this warning is displayed but may not validate.
Starting in 3.0, some of the FEED setting names were changed to more explicitly refer to the Atom feeds they inherently represent (much like the FEED_RSS setting names). Here is an exact list of the renamed setting names:
FEED -> FEED_ATOM
TAG_FEED -> TAG_FEED_ATOM
CATEGORY_FEED -> CATEGORY_FEED_ATOM
Older 2.x themes that referenced the old setting names may not link properly. In order to rectify this, please update your theme for compatibility with 3.0+ by changing the relevant values in your template files. For an example of complete feed headers and usage please check out the simple theme.
Here are some tips about Pelican that you might find useful.
GitHub comes with an interesting “pages” feature: you can upload things there and it will be available directly from their servers. As Pelican is a static file generator, we can take advantage of this.
GitHub allows you to create user pages in the form of username.github.com. Whatever is created in the master branch will be published. For this purpose, just the output generated by Pelican needs to pushed to GitHub.
So given a repository containing your articles, just run Pelican over the posts and deploy the master branch to GitHub:
$ pelican -s pelican.conf.py ./path/to/posts -o /path/to/output
Now add all the files in the output directory generated by Pelican:
$ git add /path/to/output/*
$ git commit -am "Your Message"
$ git push origin master
For creating Project pages, a branch called gh-pages is used for publishing. The excellent ghp-import makes this really easy, which can be installed via:
$ pip install ghp-import
Then, given a repository containing your articles, you would simply run Pelican and upload the output to GitHub:
$ pelican -s pelican.conf.py .
$ ghp-import output
$ git push origin gh-pages
And that’s it.
If you want, you can put that directly into a post-commit hook, so each time you commit, your blog is up-to-date on GitHub!
Put the following into .git/hooks/post-commit:
pelican -s pelican.conf.py . && ghp-import output && git push origin gh-pages