PELICAN-THEMING(1)

💖 NAME 💖

okay so this is pelican-theming(1), aka the Pelican manual page about creating themes, and bestie it’s giving main character energy ✨ Pelican is the static site generator, themes are the fit it wears, and this page is the whole tutorial.

There’s a community-managed repository of Pelican Themes at https://github.com/getpelican/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 — no cap, that’s just how community stuff works 💅

Community themes can also be found on PyPI tagged with Framework :: Pelican :: Themes at https://pypi.org/search/?q=&o=-created&c=Framework+%3A%3A+Pelican+%3A%3A+Themes 🎀

---

🦋 CREATING THEMES 🦋

To generate its HTML output, Pelican uses the Jinja templating engine — https://palletsprojects.com/p/jinja/ — because it’s flexible and the syntax is straightforward, periodt ✨ If you want to create your own theme, feel free to take inspiration from the "simple" theme at https://github.com/getpelican/pelican/tree/main/pelican/themes/simple/templates 👑

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
    ├── 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
    ├── period_archives.html  // to display time-period archives
    ├── tag.html              // processed for each tag
    └── tags.html             // must list all the tags. Can be a tag cloud.

• static contains all the static assets, which will be copied to the output theme folder. The above filesystem layout includes CSS and image folders, but those are just examples. Put what you need here 🎀
• templates contains all the templates that will be used to generate the content. The template files listed above are mandatory; you can add your own templates if it helps you keep things organized while creating your theme ✨

🌸 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.

• 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 🗓️
• hidden_articles — The list of hidden articles 🙈
• drafts — The list of draft articles 📝
• period_archives — A dictionary containing elements related to time-period archives (if enabled). See the section Listing and Linking to Period Archives for details 🗂️
• authors — A list of (author, articles) tuples, containing all the authors and corresponding articles (values) 👑
• categories — A list of (category, articles) tuples, containing all the categories and corresponding articles (values) 🏷️
• tags — A list of (tag, articles) tuples, containing all the tags and corresponding articles (values) 🌈
• pages — The list of pages 📚
• hidden_pages — The list of hidden pages 🙈
• draft_pages — The 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 at https://jinja.palletsprojects.com/en/latest/templates/#sort 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 — https://docs.python.org/3/library/datetime.html#datetime-objects. 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 at https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior, 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') }}

🔌 Checking Loaded Plugins 🔌

Pelican provides a plugin_enabled Jinja test for checking if a certain plugin is enabled. This test accepts a plugin name as a string and will return a Boolean. Namespace plugins can be specified by full name (pelican.plugins.plugin_name) or short name (plugin_name). The following example uses the webassets plugin to minify CSS if the plugin is enabled and otherwise falls back to regular CSS:

{% if "webassets" is plugin_enabled %}
    {% assets filters="cssmin", output="css/style.min.css", "css/style.scss" %}
        <link rel="stylesheet" href="{{SITEURL}}/{{ASSET_URL}}">
    {% endassets %}
{% else %}
    <link rel="stylesheet" href="{{SITEURL}}/css/style.css}">
{% endif %}

🏠 index.html 🏠

This is the home page or index of your blog, generated at index.html 💖

okay so if pagination is active, the follow-up pages will live in index{number}.html — that's the pattern, bestie ✨

and here's the variable lineup for those index.html pagination vibes:

• 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 gets processed for each of the existing authors, with output generated according to the AUTHOR_SAVE_AS setting (Default: author/{slug}.html). and yes, if pagination is active, subsequent pages will by default reside at author/{slug}{number}.html — she's consistent, periodt 🎀

here's the whole roster for author.html, no cap:

• 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

Okay bestie, this one gets processed once for every category you've got, and the output lands wherever your CATEGORY_SAVE_AS setting says it should (Default: category/{slug}.html). And if pagination is active? Subsequent pages lowkey just live at category/{slug}{number}.html by default. ✨

Here's your variable lineup, no cap:

• category — the name of the category currently being processed 🎀
• articles — the articles for this category
• dates — the 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 that page does not exist)
• articles_next_page — the next page of articles (None if that 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 that page does not exist)
• dates_next_page — the next page of articles, ordered by date, ascending (None if that page does not exist)
• page_name — CATEGORY_URL where everything after {slug} is removed — super useful for pagination links 👑

That page_name one is genuinely such a slay for building your pagination links, iykyk.

---

🌸 article.html

This template gets processed for each article, with the output generated according to the ARTICLE_SAVE_AS setting (Default: {slug}.html). The following variables are available when rendering:

• article — the article object to be displayed
• category — the name of the category for the current article

Now here's the fun part, bestie 💖 — any metadata you put in the header of the article source file is literally available as fields on the article object. The field name is the same as the name of the metadata field, except in all-lowercase characters. So FacebookImage becomes facebookimage, and so on. Cute, right?

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 }}"/>

Not me being obsessed with per-article og:images 😭 it's giving main character energy fr fr.

---

🧚 page.html

This template gets 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:

• page — the page object to be displayed. You can access its title, slug, and content. 🫶

Short and sweet, just like a standalone page should be. 💅

🏷️ tag.html

okay so this one gets processed once for every tag, and the output goes wherever your TAG_SAVE_AS setting says (default is tag/{slug}.html, slay). And if pagination is turned on? The later pages just chill at tag/{slug}{number}.html by default. periodt.

Here's everything you get to play with:

• tag — the actual name of the tag being processed, bestie
• articles — all the articles that are related to this tag
• dates — same articles, same 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 that page does not exist, tragic)
• articles_next_page — the next page of articles (None if that page doesn't exist either)
• 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 the page does not exist)
• dates_next_page — the next page of articles, ordered by date, ascending (None if the page does not exist)
• page_name — this one is TAG_URL with everything after {slug} chopped off — super useful for pagination links, iykyk 💅

---

📅 period_archives.html

This template gets processed for each year of your posts if a path for YEAR_ARCHIVE_SAVE_AS is defined, for each month if MONTH_ARCHIVE_SAVE_AS is defined, and for each day if DAY_ARCHIVE_SAVE_AS is defined. Very "every era gets its own scrapbook page" energy ✨

• period — a tuple of the form (year, month, day) that says which time period we're on. 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_num — a tuple of the form (year, month, day), exactly like period, except all the values are numbers. no strings attached, literally 🫶

You can see an example of how to use period in the "simple" theme period_archives.html template at https://github.com/getpelican/pelican/blob/main/pelican/themes/simple/templates/period_archives.html.

---

🔗 Listing and Linking to Period Archives

The period_archives variable? iconic. It can be used to generate a list of links to the whole set of period archives that Pelican generates. And because it's a common variable, it's available for use in any template — so you can build that index in a custom direct template, or in a sidebar that's visible across different site pages. main character variable behavior, honestly 👑

period_archives is a dict that may contain year, month, and/or day keys, depending on which *_ARCHIVE_SAVE_AS settings are enabled. The corresponding value is a list of dicts, where each dict in turn represents a time period (ordered according to the NEWEST_FIRST_ARCHIVES setting) with these keys and values:

• period — the same tuple as described in period_archives.html, e.g. (2023, 'June', 18).
• period_num — the same tuple as described in period_archives.html, e.g. (2023, 6, 18).
• url — the URL to the period archive page, e.g. posts/2023/06/18/. This is controlled by the corresponding *_ARCHIVE_URL setting.
• save_as — the path to the save location of the period archive page file, e.g. posts/2023/06/18/index.html. This is used internally by Pelican and is usually not relevant to themes.
• articles — a list of Article objects that fall under the time period.
• dates — same list as articles, but ordered according to the NEWEST_FIRST_ARCHIVES setting.

Here is an example of how period_archives can be used in a template:

          <ul>
          {% for archive in period_archives.month %}
              <li>
                  <a href="{{ SITEURL }}/{{ archive.url }}">
                      {{ archive.period | reverse | join(' ') }} ({{ archive.articles|count }})
                  </a>
              </li>
          {% endfor %}
          </ul>

bestie you can literally just swap period_archives.month in that for statement for period_archives.year or period_archives.day and it works 💅 — pick whichever one matches the time-period granularity you actually want. level of detail is your call, no cap.

🦋 Objects

okay so this is the good part — the actual attributes you get to play with in your templates. important caveat tho: this is not the whole list, just a curated little selection of the ones that are genuinely useful in a template. so don't come for me if something's missing 🙈

🌸 Article

the string representation of an Article is the source_path attribute. iconic.

• 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
• relative_source_path — relative path from PATH <settings.html#PATH> to 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

these three are besties fr — the string representation of all of those objects is the name attribute. slay.

• name — name of this object [1]
• page_name — author page name
• save_as — location to save the author page
• slug — page slug
• url — URL to the author page

[1] for the Author object, this comes from :authors: or AUTHOR. iykyk 💅

💅 Page 💅

Okay bestie, so the string representation of a Page is literally the source_path attribute. Here’s the whole iconique attribute lineup, no cap:

• author — the Author of this page.
• content — the rendered content of the page.
• date — a Datetime object representing the page date.
• date_format — either the default date format or the 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.
• relative_source_path — relative path from PATH (settings.html#PATH) to the page source file.
• status — the page status, can be any of 'published', 'hidden' 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.

---

✨ Feeds ✨

So the feed variables changed in 3.0, bestie. Each variable now explicitly lists ATOM or RSS in the name. ATOM is still the default. Old themes will need to be updated. Here’s the complete list of the feed variables:

AUTHOR_FEED_ATOM
AUTHOR_FEED_RSS
CATEGORY_FEED_ATOM
CATEGORY_FEED_RSS
FEED_ALL_ATOM
FEED_ALL_RSS
FEED_ATOM
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. Slay.

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. Literally saving you so much time.

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 one file. One. File. Obsessed.

🎀 main.css 🎀

The file is static/css/main.css (the default CSS_FILE):

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 ;
}

---

🧚 Custom templates 🧚

If you want to customise the templates as well, you can extend them. For example, to add a custom footer, create a templates/base.html:

{% extends "!simple/base.html" %}

{% block footer %}
    <p>Custom footer</p>
{{ super() }}
{% 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 footer block which has already been defined in the simple theme.
3. On the fourth line, we insert the extra footer content.
4. On the fifth line, the function super() keeps the content previously inserted in the head block.
5. On the last line, we close the footer block.

This file will be extended by all the other templates, so the custom footer will appear on all pages. Main character energy for your footer, fr fr.

---

💖 Author 💖

The Pelican contributors

---

🌈 Copyright 🌈

2010–2026

---

That’s the whole page, bestie 🫶 — sourced from PELICAN-THEMING(1), dated Oct 04, 2026. Mwah! 💋✨