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:
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.
Variable |
Description |
output_file |
The name of the file currently being generated. For
instance, when Pelican is rendering the home page,
output_file will be “index.html”. |
articles |
The 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. |
dates |
The same list of articles, but ordered by date,
ascending. |
drafts |
The list of draft articles |
tags |
A list of (tag, articles) tuples, containing all
the tags. |
categories |
A list of (category, articles) tuples, containing
all the categories and corresponding articles (values) |
pages |
The list of pages |
hidden_pages |
The list of hidden 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.
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.
Variable |
Description |
articles_paginator |
A paginator object for the list of articles |
articles_page |
The current page of articles |
articles_previous_page |
The previous page of articles (None if page does
not exist) |
articles_next_page |
The next page of articles (None if page does
not exist) |
dates_paginator |
A paginator object for the article list, ordered by
date, ascending. |
dates_page |
The current page of articles, ordered by date,
ascending. |
dates_previous_page |
The previous page of articles, ordered by date,
ascending (None if page does not exist) |
dates_next_page |
The 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/{author_name}.html). If pagination is active, subsequent pages will by
default reside at author/{author_name}{number}.html.
Variable |
Description |
author |
The name of the author being processed |
articles |
Articles by this author |
dates |
Articles by this author, but ordered by date,
ascending |
articles_paginator |
A paginator object for the list of articles |
articles_page |
The current page of articles |
articles_previous_page |
The previous page of articles (None if page does
not exist) |
articles_next_page |
The next page of articles (None if page does
not exist) |
dates_paginator |
A paginator object for the article list, ordered by
date, ascending. |
dates_page |
The current page of articles, ordered by date,
ascending. |
dates_previous_page |
The previous page of articles, ordered by date,
ascending (None if page does not exist) |
dates_next_page |
The next page of articles, ordered by date,
ascending (None if page does not exist) |
page_name |
AUTHOR_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/{category_name}.html). If pagination is active, subsequent pages will by
default reside at category/{category_name}{number}.html.
Variable |
Description |
category |
The name of the category being processed |
articles |
Articles for this category |
dates |
Articles for this category, but ordered by date,
ascending |
articles_paginator |
A paginator object for the list of articles |
articles_page |
The current page of articles |
articles_previous_page |
The previous page of articles (None if page does
not exist) |
articles_next_page |
The next page of articles (None if page does
not exist) |
dates_paginator |
A paginator object for the list of articles,
ordered by date, ascending |
dates_page |
The current page of articles, ordered by date,
ascending |
dates_previous_page |
The previous page of articles, ordered by date,
ascending (None if page does not exist) |
dates_next_page |
The next page of articles, ordered by date,
ascending (None if page does not exist) |
page_name |
CATEGORY_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:
{article_name}.html). The following variables are available when
rendering.
Variable |
Description |
article |
The article object to be displayed |
category |
The 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/{page_name}.html). The following variables are available when
rendering.
Variable |
Description |
page |
The 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/{tag_name}.html). If pagination is active, subsequent pages will by
default reside at tag/{tag_name}{number}.html.
Variable |
Description |
tag |
The name of the tag being processed |
articles |
Articles related to this tag |
dates |
Articles related to this tag, but ordered by date,
ascending |
articles_paginator |
A paginator object for the list of articles |
articles_page |
The current page of articles |
articles_previous_page |
The previous page of articles (None if page does
not exist) |
articles_next_page |
The next page of articles (None if page does
not exist) |
dates_paginator |
A paginator object for the list of articles,
ordered by date, ascending |
dates_page |
The current page of articles, ordered by date,
ascending |
dates_previous_page |
The previous page of articles, ordered by date,
ascending (None if page does not exist) |
dates_next_page |
The next page of articles, ordered by date,
ascending (None if page does not exist) |
page_name |
TAG_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.
Variable |
Description |
period |
A 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. |
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.
Attribute |
Description |
author |
The Author of
this article. |
authors |
A list of Authors
of this article. |
category |
The Category
of this article. |
content |
The rendered content of the article. |
date |
Datetime object representing the article date. |
date_format |
Either default date format or locale date format. |
default_template |
Default template name. |
in_default_lang |
Boolean representing if the article is written
in the default language. |
lang |
Language of the article. |
locale_date |
Date formatted by the date_format. |
metadata |
Article header metadata dict. |
save_as |
Location to save the article page. |
slug |
Page slug. |
source_path |
Full system path of the article source file. |
status |
The article status, can be any of ‘published’ or
‘draft’. |
summary |
Rendered summary content. |
tags |
List of Tag
objects. |
template |
Template name to use for rendering. |
title |
Title of the article. |
translations |
List of translations
Article objects. |
url |
URL to the article page. |
Author / Category / Tag
The string representation of those objects is the name attribute.
Attribute |
Description |
name |
Name of this object . |
page_name |
Author page name. |
save_as |
Location to save the author page. |
slug |
Page slug. |
url |
URL to the author page. |
Page
The string representation of a Page is the source_path attribute.
Attribute |
Description |
author |
The Author of
this page. |
content |
The rendered content of the page. |
date |
Datetime object representing the page date. |
date_format |
Either default date format or locale date format. |
default_template |
Default template name. |
in_default_lang |
Boolean representing if the article is written
in the default language. |
lang |
Language of the article. |
locale_date |
Date formatted by the date_format. |
metadata |
Page header metadata dict. |
save_as |
Location to save the page. |
slug |
Page slug. |
source_path |
Full system path of the page source file. |
status |
The page status, can be any of ‘published’ or
‘draft’. |
summary |
Rendered summary content. |
tags |
List of Tag
objects. |
template |
Template name to use for rendering. |
title |
Title of the page. |
translations |
List of translations
Article objects. |
url |
URL to the page. |
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 %}
- On the first line, we extend the base.html template from the simple
theme, so we don’t have to rewrite the entire file.
- On the third line, we open the head block which has already been defined
in the simple theme.
- On the fourth line, the function super() keeps the content previously
inserted in the head block.
- On the fifth line, we append a stylesheet to the page.
- 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.