Page Breaks in Pelican

A common requirement of blogging software is to be able to show a shortened version of the post on the index page so readers have an idea of what the post is about before reading the whole thing.

Methods

There are three ways of doing this using Pelican that I’m aware of. Two of them are internal and one is a plugin. I’ll list them in order of precedence.

Each of these methods will put the shortened version into the summary attribute of the article so it can be accessed using {{ article.summary }}.

Metadata key

If you only need a line as your summary, you can specify a Summary key in the article’s metadata.

Title: Page Breaks in Pelican
Date: 2013-12-06 13:21
Author: Andrei Vacariu
Summary: An article about page breaks and summaries using Pelican.

This method has highest precedence. If the Summary key is found, nothing else will be put in summary.

True page breaks using the summary plugin

The summary plugin is available in the pelican-plugins repository on GitHub.

This plugin allows you to specify a part of your article as the summary using <!-- PELICAN_BEGIN_SUMMARY --> and <!-- PELICAN_END_SUMMARY -->. Either of these two strings can be ommitted, and when it is, it’s replaced with either the top or bottom of the article as appropriate.

Now we can specify a page break in the article:

Title: Page Breaks in Pelican
Date: 2013-12-06 13:21
Author: Andrei Vacariu

A common requirement of blogging software is to be able to show a shortened
version of the post on the index page so readers have an idea of what the
post is about before reading the whole thing.
<!-- PELICAN_END_SUMMARY -->

There are three ways of doing this using Pelican that I'm aware of. Two of
them are internal and one is a plugin. I'll list them in order of
precedence.

Since <!-- PELICAN_BEGIN_SUMMARY --> is missing, it’s assumed that the summary should begin at the top of the article and continue until <!-- PELICAN_END_SUMMARY --> is found. The tag is omitted from the summary, but shows up in the article content (but since it’s an HTML comment tag, it won’t be visible).

This plugin takes precedence over SUMMARY_MAX_LENGTH when the tags are present but does nothing if they’re not there. If the Summary key is found in the metadata, though, this plugin does nothing.

Fixed length for summary

Like the first method, this method is also part of core Pelican. It will only apply when the previous two methods don’t override it.

If Summary: is not specified and you’re not using the summary plugin, Pelican has a fallback. When you attempt to access {{ article.summary }}, it will truncate the article content to 50 words. This value can be adjusted using SUMMARY_MAX_LENGTH in pelicanconf.py.

What I do

  • Ignore Summary: as I find it very limiting and I like longer summaries.
  • Use SUMMARY_MAX_LENGTH = 100 in my pelicanconf.py for most articles.
  • If there is code that would be broken in an awkward place, or I just don’t like where Pelican split the content, I use the summary plugin.
Published on December 06, 2013.