Pelican
Docs » Themes
Themes
There is a community-managed repository of Pelican Themes for people to share and use.
Please note that while we do our best to review and merge theme contributions, they are submitted by the Pelican community and thus may have varying levels of support and interoperability.
Creating Themes
To generate its HTML output, Pelican uses the Jinja templating engine due to its flexibility and straightforward syntax. If you want to create your own theme, feel free to take inspiration from the “simple” theme.
To generate your site using a theme you have created (or downloaded manually and then modified), you can specify that theme via the -t flag:
pelican content -s pelicanconf.py -t /​projects​/​your​-​site​/​themes​/​your​-​theme
If you’d rather not specify the theme on every invocation, you can define THEME in your settings to point to the location of your preferred theme.
Structure
To make your own theme, you must follow the following structure:
├── static │   ├── css │   └── images └── templates ├── archives.html // to display archives ├── period_archives.html // to display time-period archives ├── article.html // processed for each article ├── author.html // processed for each author ├── authors.html // must list all the authors ├── categories.html // must list all the categories ├── category.html // processed for each category ├── index.html // the index (list all the articles) ├── page.html // processed for each page ├── tag.html // processed for each tag └── tags.html // must list all the tags. Can be a tag cloud.
Templates and Variables
The idea is to use a simple syntax that you can embed into your HTML pages. This document describes which templates should exist in a theme, and which variables will be passed to each template at generation time.
All templates will receive the variables defined in your settings file, as long as they are in all-caps. You can access them directly.
Common Variables
All of these settings will be available to all templates.
VariableDescription
output_fileThe name of the file currently being generated. For instance, when Pelican is rendering the home page, output_file will be “index.html”.
articlesThe list of articles, ordered descending by date. All the elements are Article objects, so you can access their attributes (e.g. title, summary, author etc.). Sometimes this is shadowed (for instance, in the tags page). You will then find info about it in the all_articles variable.
datesThe same list of articles, but ordered by date, ascending.
hidden_articlesThe list of hidden articles
draftsThe list of draft articles
authorsA list of (author, articles) tuples, containing all the authors and corresponding articles (values)
categoriesA list of (category, articles) tuples, containing all the categories and corresponding articles (values)
tagsA list of (tag, articles) tuples, containing all the tags and corresponding articles (values)
pagesThe list of pages
hidden_pagesThe list of hidden pages
draft_pagesThe list of draft pages
Sorting
URL wrappers (currently categories, tags, and authors), have comparison methods that allow them to be easily sorted by name:
{% for tag, articles in tags|sort %}
If you want to sort based on different criteria, Jinja’s sort command has a number of options.
Date Formatting
Pelican formats the date according to your settings and locale (​DATE_FORMATS​/​DEFAULT_DATE_FORMAT​) and provides a locale_date attribute. On the other hand, the date attribute will be a datetime object. If you need custom formatting for a date different than your settings, use the Jinja filter strftime that comes with Pelican. Usage is same as Python strftime format, but the filter will do the right thing and format your date according to the locale given in your settings:
{{ article.date|strftime('%d %B %Y') }}
index.html
This is the home page or index of your blog, generated at index.html.
If pagination is active, subsequent pages will reside in index{number}.html.
VariableDescription
articles_paginatorA paginator object for the list of articles
articles_pageThe current page of articles
articles_previous_pageThe previous page of articles (None if page does not exist)
articles_next_pageThe next page of articles (None if page does not exist)
dates_paginatorA paginator object for the article list, ordered by date, ascending.
dates_pageThe current page of articles, ordered by date, ascending.
dates_previous_pageThe previous page of articles, ordered by date, ascending (None if page does not exist)
dates_next_pageThe next page of articles, ordered by date, ascending (None if page does not exist)
page_name‘index’ – useful for pagination links
author.html
This template will be processed for each of the existing authors, with output generated according to the AUTHOR_SAVE_AS setting (Default: author/{slug}.html). If pagination is active, subsequent pages will by default reside at author/{slug}{number}.html.
VariableDescription
authorThe name of the author being processed
articlesArticles by this author
datesArticles by this author, but ordered by date, ascending
articles_paginatorA paginator object for the list of articles
articles_pageThe current page of articles
articles_previous_pageThe previous page of articles (None if page does not exist)
articles_next_pageThe next page of articles (None if page does not exist)
dates_paginatorA paginator object for the article list, ordered by date, ascending.
dates_pageThe current page of articles, ordered by date, ascending.
dates_previous_pageThe previous page of articles, ordered by date, ascending (None if page does not exist)
dates_next_pageThe next page of articles, ordered by date, ascending (None if page does not exist)
page_nameAUTHOR_URL where everything after {slug} is removed – useful for pagination links
category.html
This template will be processed for each of the existing categories, with output generated according to the CATEGORY_SAVE_AS setting (Default: category/{slug}.html). If pagination is active, subsequent pages will by default reside at category/{slug}{number}.html​.
VariableDescription
categoryThe name of the category being processed
articlesArticles for this category
datesArticles for this category, but ordered by date, ascending
articles_paginatorA paginator object for the list of articles
articles_pageThe current page of articles
articles_previous_pageThe previous page of articles (None if page does not exist)
articles_next_pageThe next page of articles (None if page does not exist)
dates_paginatorA paginator object for the list of articles, ordered by date, ascending
dates_pageThe current page of articles, ordered by date, ascending
dates_previous_pageThe previous page of articles, ordered by date, ascending (None if page does not exist)
dates_next_pageThe next page of articles, ordered by date, ascending (None if page does not exist)
page_nameCATEGORY_URL where everything after {slug} is removed – useful for pagination links
article.html
This template will be processed for each article, with output generated according to the ARTICLE_SAVE_AS setting (Default:{slug}.html). The following variables are available when rendering.
VariableDescription
articleThe article object to be displayed
categoryThe name of the category for the current article
Any metadata that you put in the header of the article source file will be available as fields on the article object. The field name will be the same as the name of the metadata field, except in all-lowercase characters.
For example, you could add a field called FacebookImage to your article metadata, as shown below:
Title: I love Python more than music Date: 2013-11-06 10:06 Tags: personal, python Category: Tech Slug: python-je-l-aime-a-mourir Author: Francis Cabrel FacebookImage: http://franciscabrel.com/images/pythonlove.png
This new metadata will be made available as article.facebookimage in your article.html template. This would allow you, for example, to specify an image for the Facebook open graph tags that will change for each article:
<meta property="og:image" content="{{ article.facebookimage }}"/>
page.html
This template will be processed for each page, with output generated according to the PAGE_SAVE_AS setting (​Default:​pages/{slug}.html​). The following variables are available when rendering.
VariableDescription
pageThe page object to be displayed. You can access its title, slug, and content.
tag.html
This template will be processed for each tag, with output generated according to the TAG_SAVE_AS setting (Default:tag/{slug}.html). If pagination is active, subsequent pages will by default reside at tag/{slug}{number}.html.
VariableDescription
tagThe name of the tag being processed
articlesArticles related to this tag
datesArticles related to this tag, but ordered by date, ascending
articles_paginatorA paginator object for the list of articles
articles_pageThe current page of articles
articles_previous_pageThe previous page of articles (None if page does not exist)
articles_next_pageThe next page of articles (None if page does not exist)
dates_paginatorA paginator object for the list of articles, ordered by date, ascending
dates_pageThe current page of articles, ordered by date, ascending
dates_previous_pageThe previous page of articles, ordered by date, ascending (None if page does not exist)
dates_next_pageThe next page of articles, ordered by date, ascending (None if page does not exist)
page_nameTAG_URL where everything after {slug} is removed – useful for pagination links
period_archives.html
This template will be processed for each year of your posts if a path for YEAR_ARCHIVE_SAVE_AS is defined, each month if MONTH_ARCHIVE_SAVE_AS is defined, and each day if DAY_ARCHIVE_SAVE_AS is defined.
VariableDescription
periodA tuple of the form (year, month, day) that indicates the current time period. year and day are numbers while month is a string. This tuple only contains year if the time period is a given year. It contains both year and month if the time period is over years and months and so on.
period_numA tuple of the form (year, month, day), as in period, except all values are numbers.
You can see an example of how to use period in the “simple” theme period_archives.html template.
Objects
Detail objects attributes that are available and useful in templates. Not all attributes are listed here, this is a selection of attributes considered useful in a template.
Article
The string representation of an Article is the source_path attribute.
AttributeDescription
authorThe Author of this article.
authorsA list of Authors of this article.
categoryThe Category of this article.
contentThe rendered content of the article.
dateDatetime object representing the article date.
date_formatEither default date format or locale date format.
default_templateDefault template name.
in_default_langBoolean representing if the article is written in the default language.
langLanguage of the article.
locale_dateDate formatted by the date_format.
metadataArticle header metadata dict.
save_asLocation to save the article page.
slugPage slug.
source_pathFull system path of the article source file.
relative_source_pathRelative path from PATH to the article source file.
statusThe article status, can be any of ‘published’ or ‘draft’.
summaryRendered summary content.
tagsList of Tag objects.
templateTemplate name to use for rendering.
titleTitle of the article.
translationsList of translations Article objects.
urlURL to the article page.
Author / Category / Tag
The string representation of those objects is the name attribute.
AttributeDescription
nameName of this object [1].
page_nameAuthor page name.
save_asLocation to save the author page.
slugPage slug.
urlURL to the author page.
[1]for Author object, coming from :authors: or AUTHOR.
Page
The string representation of a Page is the source_path attribute.
AttributeDescription
authorThe Author of this page.
contentThe rendered content of the page.
dateDatetime object representing the page date.
date_formatEither default date format or locale date format.
default_templateDefault template name.
in_default_langBoolean representing if the article is written in the default language.
langLanguage of the article.
locale_dateDate formatted by the date_format.
metadataPage header metadata dict.
save_asLocation to save the page.
slugPage slug.
source_pathFull system path of the page source file.
relative_source_pathRelative path from PATH to the page source file.
statusThe page status, can be any of ‘published’, ‘hidden’ or ‘draft’.
summaryRendered summary content.
tagsList of Tag objects.
templateTemplate name to use for rendering.
titleTitle of the page.
translationsList of translations Article objects.
urlURL to the page.
Feeds
The feed variables changed in 3.0. Each variable now explicitly lists ATOM or RSS in the name. ATOM is still the default. Old themes will need to be updated. Here is a complete list of the feed variables:
FEED_ATOM​FEED_RSS​FEED_ALL_ATOM​FEED_ALL_RSS​CATEGORY_FEED_ATOM​CATEGORY_FEED_RSS​AUTHOR_FEED_ATOM​AUTHOR_FEED_RSS​TAG_FEED_ATOM​TAG_FEED_RSS​TRANSLATION_FEED_ATOM​TRANSLATION_FEED_RSS
Inheritance
Since version 3.0, Pelican supports inheritance from the simple theme, so you can re-use the simple theme templates in your own themes.
If one of the mandatory files in the templates/ directory of your theme is missing, it will be replaced by the matching template from the simple theme. So if the HTML structure of a template in the simple theme is right for you, you don’t have to write a new template from scratch.
You can also extend templates from the simple theme in your own themes by using the
{% extends %}
directive as in the following example:
{% extends "!simple/index.html" %} <!-- extends the ``index.html`` template from the ``simple`` theme -->{% extends "index.html" %} <!-- "regular" extending -->
Example
With this system, it is possible to create a theme with just two files.
base.html
The first file is the templates/base.html template:
{% extends "!simple/base.html" %}{% block head %}{{ super() }} <link rel="stylesheet" type="text/css" href="{{ SITEURL }}/theme/css/style.css" />{% endblock %}
  1. On the first line, we extend the base.html template from the simple theme, so we don’t have to rewrite the entire file.
  2. On the third line, we open the head block which has already been defined in the simple theme.
  3. On the fourth line, the function super() keeps the content previously inserted in the head block.
  4. On the fifth line, we append a stylesheet to the page.
  5. On the last line, we close the head block.
This file will be extended by all the other templates, so the stylesheet will be linked from all pages.
style.css
The second file is the static/css/style.css CSS stylesheet:
body { font-family : monospace ; font-size : 100% ; background-color : white ; color : #111 ; width : 80% ; min-width : 400px ; min-height : 200px ; padding : 1em ; margin : 5% 10% ; border : thin solid gray ; border-radius : 5px ; display : block ;}a:link { color : blue ; text-decoration : none ; }a:hover { color : blue ; text-decoration : underline ; }a:visited { color : blue ; }h1 a { color : inherit !important }h2 a { color : inherit !important }h3 a { color : inherit !important }h4 a { color : inherit !important }h5 a { color : inherit !important }h6 a { color : inherit !important }pre { margin : 2em 1em 2em 4em ;}#menu li { display : inline ;}#post-list { margin-bottom : 1em ; margin-top : 1em ;}
Download
You can download this example theme here.
Next
Previous
Uncountable: a bootstrapped company building real-world scientific tools Join our fullstack team
Ad by EthicalAds   ·   Monetize your site
© Copyright 2010 – present, Justin Mayer, Alexis Metaireau, and contributors Revision bb10d286.
Built with Sphinx using a theme provided by Read the Docs.
Pelican QuickstartInstalling PelicanWriting contentPublish your siteSettingsPluginsCreating ThemesStructureTemplates and VariablesCommon VariablesSortingDate Formattingindex.htmlauthor.htmlcategory.htmlarticle.htmlpage.htmltag.htmlperiod_archives.htmlObjectsArticleAuthor / Category / TagPageFeedsInheritanceExamplepelican-themesImporting an existing siteFrequently Asked Questions (FAQ)TipsContributing and feedback guidelinesPelican internalsSome history about PelicanRelease history
Pelican