Setting Up a static recipe website with Pelican and tuxlite_recipes

This guide walks you through building a responsive recipe website from scratch using Pelican — a static site generator written in Python and the tuxlite_recipes theme. No prior knowledge of Pelican is assumed.

---

What You Will Need

• A computer running Linux, macOS, or Windows (with WSL recommended on Windows)
• Python 3.10 or newer (download here)
• Git (download here)
• A terminal / command prompt

To verify Python and Git are installed and ready, open a terminal and run:

python3 --version
git --version

Both commands should print a version number. If they don’t, install the missing tool before continuing.

---

Part 1 — Install Pelican

It is best practice to keep Pelican and its dependencies in an isolated Python virtual environment, so they don’t interfere with other Python projects on your system.

Step 1: Create a project folder

Choose a location where your recipe site will live and create a folder for it:

mkdir my-recipe-site
cd my-recipe-site

Step 2: Create and activate a virtual environment

python3 -m venv tuxlite_venv

Then activate it:

• Linux / macOS:

  source tuxlite_venv/bin/activate

• Windows (WSL or Git Bash):

  source tuxlite_venv/bin/activate

• Windows (Command Prompt):

  venv\Scripts\activate.bat

Your prompt should now show (venv) at the beginning, confirming the environment is active. Always activate this environment before working on your site.

Step 3: Install Pelican and Markdown support

pip install "pelican[markdown]"

This installs Pelican along with the Markdown parser, which lets you write recipes in the friendly Markdown format instead of reStructuredText.

---

Part 2 — Create a New Pelican Site

Pelican ships with a quickstart wizard that builds the basic site structure for you.

Step 4: Run the quickstart wizard

From inside your my-recipe-site folder (with the virtual environment active), run:

pelican-quickstart

You will be asked a series of questions. Here is an example session with recommended answers:

> Where do you want to create your new web site? [.] 
  → Press Enter (use current directory)

> What will be the title of this web site?
  → My Recipe Collection

> Who will be the author of this web site?
  → Your Name

> What will be the default language of this web site? [en]
  → Press Enter

> Do you want to specify a URL prefix? e.g., https://example.com (Y/n)
  → n  (you can set this later)

> Do you want to enable article pagination? (Y/n)
  → Y

> How many articles per page do you want? [10]
  → Press Enter

> What is your time zone? [Europe/Rome]
  → Enter your time zone, e.g. Europe/London or America/New_York

> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n)
  → Y

> Do you want to upload your website using FTP? (y/N)  → n
> Do you want to upload your website using SSH? (y/N)  → n
> Do you want to upload your website using Dropbox? (y/N) → n
> Do you want to upload your website using S3? (y/N) → n
> Do you want to upload your website using Rackspace Cloud Files? (y/N) → n
> Do you want to upload your website using GitHub Pages? (y/N) → n

When the wizard finishes, your project folder will look like this:

my-recipe-site/
├── content/          ← your recipes go here
├── output/           ← generated HTML (created when you build)
├── venv/             ← your virtual environment
├── pelicanconf.py    ← main settings file
├── publishconf.py    ← settings used when publishing publicly
├── Makefile
└── tasks.py

---

Part 3 — Install the tuxlite_recipes Theme

Step 5: Create a themes folder and clone the theme

mkdir themes
git clone https://codeberg.org/web_pat/tuxlite_recipes themes/tuxlite_recipes

This downloads the theme into themes/tuxlite_recipes/ inside your project.

Step 6: Tell Pelican to use the theme

Open pelicanconf.py in any text editor and add or update the THEME line:

THEME = 'themes/tuxlite_recipes'

---

Part 4 — Configure Your Site

Open pelicanconf.py. It already contains some settings from the quickstart wizard. Below is a full example configuration that works well with tuxlite_recipes — replace the placeholder values with your own:

AUTHOR = 'Your Name'
SITENAME = 'My Recipe Collection'
SITEURL = ''  # Leave blank for local development; set to your domain when publishing

PATH = 'content'

TIMEZONE = 'Europe/London'  # Change to your time zone

DEFAULT_LANG = 'en'

THEME = 'themes/tuxlite_recipes'

# Feed settings — disable for local development
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None

# Navigation links shown in the header
LINKS = (
    ('Home', '/'),
)

# Social links (optional — remove if not needed)
SOCIAL = (
    ('Mastodon', 'https://mastodon.social/@yourhandle'),
)

DEFAULT_PAGINATION = 10

# Organise content by category folder
USE_FOLDER_AS_CATEGORY = True

Save the file.

---

Part 5 — Write Your First Recipe

Recipes are written as plain text files in Markdown format and stored in the content/ folder. Pelican treats each file as an “article”.

Step 7: Create a recipe file

mkdir -p content/recipes

Create a file called content/recipes/chocolate-cake.md and open it in your text editor. Paste in the following:

Title: Classic Chocolate Cake
Date: 2024-01-15
Category: Desserts
Tags: cake, chocolate, baking
Summary: A rich and moist chocolate cake perfect for any occasion.

## Ingredients

- 200 g plain flour
- 200 g caster sugar
- 100 g unsalted butter, softened
- 2 large eggs
- 100 ml whole milk
- 50 g cocoa powder
- 1½ tsp baking powder
- 1 tsp vanilla extract
- Pinch of salt

## Method

1. Preheat your oven to 180 °C (160 °C fan). Grease and line two 20 cm round cake tins.
2. Beat the butter and sugar together until pale and fluffy.
3. Add the eggs one at a time, beating well after each addition.
4. Sift together the flour, cocoa, baking powder, and salt. Fold into the batter in three additions, alternating with the milk.
5. Stir in the vanilla extract.
6. Divide the batter evenly between the tins and bake for 25–30 minutes, until a skewer inserted into the centre comes out clean.
7. Cool in the tins for 10 minutes, then turn out onto a wire rack.

## Notes

For a richer flavour, replace 50 ml of milk with strong brewed coffee.

The lines at the top (Title, Date, Category, Tags, Summary) are metadata — Pelican uses them to organise and display your recipes correctly.

Metadata fields explained

Field	Required	Description
Title	Yes	The recipe name
Date	Yes	Publication date in YYYY-MM-DD format
Category	No	Used to group recipes (e.g., Desserts, Mains)
Tags	No	Comma-separated keywords
Summary	No	Short description shown in listings

---

Part 6 — Preview Your Site Locally

Step 8: Build and serve the site

With your virtual environment active, run:

pelican content -r &
pelican --listen

Or, if you chose to generate a Makefile, simply run:

make devserver

Then open your browser and go to:

http://localhost:8000

You should see your recipe site with the tuxlite_recipes theme applied. Every time you save a recipe file, Pelican will automatically regenerate the site — just refresh your browser.

To stop the development server, press Ctrl+C.

---

Part 7 — Organising Your Recipes

You can keep all recipes in one folder, or group them into subfolders by category. When USE_FOLDER_AS_CATEGORY = True is set in pelicanconf.py, the folder name becomes the category automatically.

Recommended folder structure:

content/
├── recipes/
│   ├── desserts/
│   │   ├── chocolate-cake.md
│   │   └── lemon-tart.md
│   ├── mains/
│   │   ├── pasta-carbonara.md
│   │   └── roast-chicken.md
│   └── starters/
│       └── tomato-soup.md
└── pages/
    └── about.md

Files in content/pages/ are treated as static pages (not recipes) and will appear in the navigation menu.

---

Part 8 — Static Files (Images)

To add photos to your recipes, create an images folder inside content/:

mkdir content/images

Copy your image there, e.g. content/images/chocolate-cake.jpg, then tell Pelican where to find static files by adding this to pelicanconf.py:

STATIC_PATHS = ['images']

In a recipe file, reference the image like this:

![Chocolate Cake]({static}/images/chocolate-cake.jpg)

The {static} tag is a Pelican shorthand that resolves to the correct path regardless of your site’s URL structure.

---

Part 9 — Building for Publication

When you are ready to publish your site, set the SITEURL in publishconf.py (not pelicanconf.py) to your actual domain:

SITEURL = 'https://www.myrecipes.example.com'
RELATIVE_URLS = False

Then build the final version:

pelican content -s publishconf.py

The output/ folder will contain all the HTML, CSS, and image files ready to upload to any web hosting provider. Since the site is entirely static, you only need a basic web host — no PHP, no database, no special server software required.

---

Troubleshooting

The site builds but looks unstyled
Make sure the THEME path in pelicanconf.py is correct and points to the folder you cloned. Run ls themes/tuxlite_recipes to confirm the folder exists.

pelican: command not found
You likely forgot to activate your virtual environment. Run source venv/bin/activate and try again.

Changes to recipes are not appearing
If you are running the dev server manually rather than with make devserver, make sure you used the -r flag (pelican content -r) to enable auto-reload.

ModuleNotFoundError: No module named 'markdown'
You installed Pelican without Markdown support. Fix this by running:

pip install "pelican[markdown]"

---

Quick Reference

Task	Command
Activate virtual environment	source venv/bin/activate
Start development server	make devserver
Build site (development)	pelican content
Build site (production)	pelican content -s publishconf.py
Stop development server	Ctrl+C

---

Further Reading

• Pelican documentation
• tuxlite_recipes theme repository
• Markdown syntax guide
• Pelican themes gallery