Written by: Geoffrey Callaghan

how to create a pelican theme

How To Create A Pelican Theme

Creating a Pelican theme involves customizing templates, stylesheets, and optionally JavaScript for your Pelican-based website or blog. Pelican is a static site generator written in Python, and themes are primarily based on Jinja2 templates and CSS. Here’s a step-by-step guide to help you create a Pelican theme:

Step 1: Set Up Your Environment

  1. Install Python and pip: Ensure you have Python installed on your system. You can download it from python.org. Pip, Python’s package installer, usually comes with Python.

  2. Install Pelican: Install Pelican using pip.

    pip install pelican
  3. Create a New Pelican Project: Initialize a new Pelican project.


    Follow the prompts to set up your project.

Step 2: Create a New Pelican Theme

  1. Set Up Your Theme Directory: Inside the themes directory of your Pelican project, create a new directory for your theme.

    cd path_to_your_pelican_project
    mkdir themes
    cd themes
    mkdir my-theme
    cd my-theme
  2. Initialize a templates Directory: Create a directory to store your theme templates.

    mkdir templates
  3. Initialize a static Directory: Create a directory to store your theme’s static files (CSS, JavaScript, images).

    mkdir static
  4. Create a theme.conf File: Create a configuration file for your theme.

    ; themes/my-theme/theme.conf
    name = My Pelican Theme
    author = Your Name

Step 3: Develop Your Pelican Theme

  1. Create Template Files: Pelican uses Jinja2 templates for rendering content. Here are some example template files you can create:

    • base.html: Base template that other templates extend.
    • index.html: Template for the homepage.
    • article.html: Template for displaying individual articles.
    • category.html: Template for category listings.
    • tag.html: Template for tag listings.
    • archives.html: Template for displaying archives.

    Example base.html:

    <!-- themes/my-theme/templates/base.html -->
    <!DOCTYPE html>
    <html lang="en">
        <meta charset="UTF-8">
        <title>{% block title %}{{ SITE_TITLE }}{% endblock %}</title>
        <link rel="stylesheet" href="{{ SITEURL }}/static/style.css">
            <h1><a href="{{ SITEURL }}">{{ SITENAME }}</a></h1>
                    <li><a href="{{ SITEURL }}">Home</a></li>
                    <li><a href="{{ SITEURL }}/archives.html">Archives</a></li>
                    <!-- Add more menu items as needed -->
            {% block content %}
            {% endblock %}
            <p>&copy; {{ now().year }} {{ SITENAME }}</p>
  2. Create Static Files (CSS, JavaScript): Add stylesheets, JavaScript files, and other static assets to your theme’s static directory.

    Example style.css:

    /* themes/my-theme/static/style.css */
    body {
        font-family: Arial, sans-serif;
        line-height: 1.6;
        background-color: #f0f0f0;
        margin: 0;
        padding: 0;
    header {
        background-color: #007bff;
        color: white;
        padding: 10px;
    nav ul {
        list-style-type: none;
        padding: 0;
    nav ul li {
        display: inline;
        margin-right: 10px;
    nav ul li a {
        color: white;
        text-decoration: none;
    main {
        padding: 20px;
    footer {
        background-color: #007bff;
        color: white;
        text-align: center;
        padding: 10px;
        position: fixed;
        bottom: 0;
        width: 100%;

Step 4: Configure Your Pelican Theme

  1. Update Pelican Configuration: Modify the pelicanconf.py file in your Pelican project to specify your theme.

    # pelicanconf.py
    THEME = 'my-theme'
  2. Customize Theme Settings: Add any additional customization options in your theme’s configuration file (theme.conf) or directly in your template files.

Step 5: Use and Test Your Pelican Theme

  1. Apply Your Theme in Your Pelican Project: Use your theme’s templates and static files to render your Pelican site.

  2. Preview Your Pelican Site: Generate your Pelican site and preview it locally.

    pelican content
    pelican --listen

    This will generate your site and start a web server to preview it in your browser.

Step 6: Publish and Share Your Pelican Theme

  1. Publish Your Theme (Optional): If you want to share your theme with others, you can publish it on GitHub, PyPI, or another platform.

Final Steps

  1. Test Your Theme: Test your theme across different content types (articles, pages, categories) to ensure it works correctly.

  2. Document Your Theme: Provide clear documentation on how to install, use, and customize your Pelican theme in a README.md file or documentation website.

By following these steps, you can create a custom Pelican theme tailored to your specific design and functional requirements, making your blog or website unique and personalized.