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

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.
Install Pelican: Install Pelican using pip.
```
pip install pelican
```
Create a New Pelican Project: Initialize a new Pelican project.
```
pelican-quickstart
```
Follow the prompts to set up your project.

Step 2: Create a New Pelican Theme

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
```
Initialize a templates Directory: Create a directory to store your theme templates.
```
mkdir templates
```
Initialize a static Directory: Create a directory to store your theme’s static files (CSS, JavaScript, images).
```
mkdir static
```

Create a theme.conf File: Create a configuration file for your theme.

; themes/my-theme/theme.conf

[theme]
name = My Pelican Theme
author = Your Name

Step 3: Develop Your Pelican Theme

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">
<head>
    <meta charset="UTF-8">
    <title>{% block title %}{{ SITE_TITLE }}{% endblock %}</title>
    <link rel="stylesheet" href="{{ SITEURL }}/static/style.css">
</head>
<body>
    <header>
        <h1><a href="{{ SITEURL }}">{{ SITENAME }}</a></h1>
        <nav>
            <ul>
                <li><a href="{{ SITEURL }}">Home</a></li>
                <li><a href="{{ SITEURL }}/archives.html">Archives</a></li>
                <!-- Add more menu items as needed -->
            </ul>
        </nav>
    </header>
    
    <main>
        {% block content %}
        {% endblock %}
    </main>
    
    <footer>
        <p>&copy; {{ now().year }} {{ SITENAME }}</p>
    </footer>
</body>
</html>

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

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

THEME = 'my-theme'
```
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

Apply Your Theme in Your Pelican Project: Use your theme’s templates and static files to render your Pelican site.
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.

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

Test Your Theme: Test your theme across different content types (articles, pages, categories) to ensure it works correctly.
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.