Migrating from Pelican

Migrating from Python-based Pelican to Rustyll? This guide will help you transition your blog or content site to high-performance Rust-powered Rustyll while preserving your content’s organization and features.

Installation

First, install Rustyll using Cargo (Rust’s package manager):

# Install Rust if you haven't already
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Rustyll
cargo install rustyll

Automatic Migration

Rustyll provides a built-in migration tool for Pelican sites:

rustyll migrate --from pelican --source ./my-pelican-site --destination ./my-rustyll-site

This command will:

Copy all content files
Convert Pelican-specific metadata to Rustyll front matter
Transform Pelican themes to Rustyll templates
Adjust configuration settings
Generate a migration report

Directory Structure Differences

Pelican	Rustyll	Notes
`content/`	Root directory and `_posts/`	Content files move to appropriate locations
`content/articles/`	`_posts/`	Blog posts
`content/pages/`	Root directory	Static pages
`pelicanconf.py`	`_config.yml`	Main configuration file
`publishconf.py`	`_config.yml` + `_config.prod.yml`	Production settings
`themes/`	`_layouts/` and `_includes/`	Theme templates
`output/`	`_site/`	Generated site

Content Format Conversion

Articles to Posts

Pelican articles convert to Rustyll posts:

# Pelican (content/articles/my-article.md)
Title: My First Article
Date: 2023-01-15 10:20
Modified: 2023-01-16 19:30
Category: Python
Tags: python, pelican, tutorial
Slug: my-first-article
Authors: Your Name
Summary: Short summary of the article

This is the content of my first article.

Converts to:

# Rustyll (_posts/2023-01-15-my-first-article.md)
---
title: My First Article
date: 2023-01-15 10:20:00
last_modified_at: 2023-01-16 19:30:00
categories:
  - Python
tags:
  - python
  - pelican
  - tutorial
slug: my-first-article
author: Your Name
excerpt: Short summary of the article
---

This is the content of my first article.

Pages to Static Pages

Pelican pages convert to Rustyll pages:

# Pelican (content/pages/about.md)
Title: About
Slug: about
Date: 2023-01-15

This is the about page.

Converts to:

# Rustyll (about.md)
---
title: About
permalink: /about/
date: 2023-01-15
layout: page
---

This is the about page.

Configuration Conversion

Pelican’s Python configuration converts to Rustyll’s YAML:

# Pelican (pelicanconf.py)
AUTHOR = 'Your Name'
SITENAME = 'My Blog'
SITEURL = 'https://example.com'

PATH = 'content'
TIMEZONE = 'Europe/Paris'
DEFAULT_LANG = 'en'

# Feed settings
FEED_ALL_ATOM = 'feeds/all.atom.xml'
CATEGORY_FEED_ATOM = 'feeds/{slug}.atom.xml'

# Blogroll
LINKS = (('Pelican', 'https://getpelican.com/'),
         ('Python.org', 'https://www.python.org/'))

# Social widget
SOCIAL = (('Twitter', 'https://twitter.com/username'),
          ('GitHub', 'https://github.com/username'))

DEFAULT_PAGINATION = 10

Converts to:

# Rustyll (_config.yml)
author: Your Name
title: My Blog
url: https://example.com

timezone: Europe/Paris
lang: en

# Feed settings
feed:
  path: feeds/all.atom.xml
  categories: true
  category_path: feeds/:name.atom.xml

# Link lists
links:
  - title: Pelican
    url: https://getpelican.com/
  - title: Python.org
    url: https://www.python.org/

social:
  - title: Twitter
    url: https://twitter.com/username
  - title: GitHub
    url: https://github.com/username

# Pagination
paginate: 10
paginate_path: "/page:num/"

Template Conversion

Pelican uses Jinja2 templates, while Rustyll uses Liquid:

Pelican (Jinja2)	Rustyll (Liquid)
`{{ article.title }}`	`{{ page.title }}`
`{% for article in articles %}`	`{% for post in site.posts %}`
`{% endfor %}`	`{% endfor %}`
`{{ article.date }}`	`{{ post.date }}`
`{% block content %}`	`{% content %}`
`{{ SITEURL }}`	`{{ site.url }}`

Plugin Conversion

Many Pelican plugins have Rustyll equivalents:

Pelican Plugin	Rustyll Equivalent
`sitemap`	`rustyll-sitemap`
`feed`	Built-in feed generation
`related_posts`	`rustyll-related-posts`
`neighbors`	Navigation includes
`assets`	Built-in asset management
`i18n_subsites`	Multilingual collections

Themes

Pelican themes convert to Rustyll layouts and includes:

Pelican Theme File	Rustyll Equivalent
`base.html`	`_layouts/default.html`
`article.html`	`_layouts/post.html`
`page.html`	`_layouts/page.html`
`index.html`	`index.html` with layout
`categories.html`	`categories.html` with layout
`tags.html`	`tags.html` with layout
`archives.html`	`archives.html` with layout

Category and Tag Pages

Pelican’s category and tag pages are implemented in Rustyll using collections:

# _config.yml
collections:
  categories:
    output: true
    permalink: /category/:name/
  tags:
    output: true
    permalink: /tag/:name/

Archives and Pagination

Pelican’s archives and pagination are handled differently in Rustyll:

# _config.yml
paginate: 10
paginate_path: "/page:num/"

# Archives configuration
archives:
  enabled: true
  layout: archive
  permalinks:
    year: '/:year/'
    month: '/:year/:month/'
    day: '/:year/:month/:day/'

Performance Improvements

Rustyll offers significant performance advantages over Python-based Pelican:

# Rustyll performance options
threads: auto  # Use all available CPU cores
incremental: true  # Enable incremental builds
cache:
  enabled: true
  strategy: aggressive

Benefits include:

Build Speed: 10-20x faster builds
Memory Usage: Significantly lower resource consumption
Parallelism: Utilizes all CPU cores efficiently

Troubleshooting Common Issues

Python Dependencies

Rustyll eliminates Python dependencies:

No need for virtualenv or requirements.txt
No Python runtime required for building
Simplified deployment workflow

Custom Jinja Filters

If you use custom Jinja filters in Pelican:

Check for equivalent Liquid filters in Rustyll
Create custom Liquid filters if needed
Simplify templates where possible

Metadata Format

If you encounter metadata conversion issues:

Check for non-standard metadata in Pelican content
Verify front matter format in converted files
Look for unsupported metadata types

Rustyll