How to Migrate a Pelican or MkDocs Site to Bengal

Migration guide: Pelican or MkDocs to Bengal. Content mapping, front matter, templates (Jinja2 to Kida), config, and common gotchas.

3 min read
lbliii

A practical migration guide. Content, metadata, templates, and config.

flowchart LR A[Pelican / MkDocs] --> B[Content mapping] B --> C[Front matter] C --> D[Templates] D --> E[Config] E --> F[bengal build]

TL;DR

  1. Map content structure to Bengal sections
  2. Convert front matter (Pelican/MkDocs → Bengal)
  3. Port templates (Jinja2 → Kida, mostly compatible)
  4. Translate config
  5. Run bengal build and fix broken links

Content mapping

Pelican

Pelican uses content/ or articles/ with metadata in the front matter. Bengal uses content/<section>/ with _index.md per section.

Pelican Bengal
content/article.md content/blog/article.md
Category: python tags: [python] in front matter
Date: 2026-03-15 date: '2026-03-15'
Slug: my-post Filename or slug in front matter

Create a section per Pelican category or put everything in blog/. Add _index.md:

---
title: Blog
type: blog
---

MkDocs

MkDocs uses docs/ and mkdocs.yml for nav. Bengal uses content/ with directory structure.

MkDocs Bengal
docs/getting-started.md content/docs/getting-started.md
docs/guides/advanced.md content/docs/guides/advanced.md
Nav in mkdocs.yml Directory structure + weight in front matter

Use weight for ordering:

---
title: Getting Started
weight: 10
---

Front matter and metadata

Bengal expects YAML front matter. Pelican uses similar keys; MkDocs uses fewer.

Key Pelican MkDocs Bengal
Title Title: First # heading title:
Date Date: File mtime date:
Tags Tags: — tags:
Category Category: — category: or section
Slug Slug: Filename Filename or slug:
Draft Status: draft — draft: true

Convert Pelican metadata to YAML. For MkDocs, add title and weight where needed.

Templates (Jinja2 → Kida)

Kida is Jinja2-like. Most syntax works: {{ variable }}, {% for %}, {% if %}, {% block %}. Differences:

  • Block end: {% end %} instead of {% endblock %}
  • Kida uses {% block name %}...{% end %} for blocks
  • Some Jinja2 filters may need reimplementation

Pelican themes are Jinja2. Port the structure; replace {% endblock %} with {% end %}. Check Kida docs for filter compatibility.

MkDocs themes (Material, etc.) are more complex. You may need to rebuild the layout in Kida. Start with Bengal's default theme and adapt.

Config and theme

Pelican uses pelicanconf.py. Bengal uses bengal.yaml or pyproject.toml:

# bengal.yaml
site:
  title: My Site
  base_url: https://example.com

MkDocs uses mkdocs.yml. Map site_name → site.title, site_url → site.base_url.

Common gotchas

  1. Trailing slashes — Bengal uses trailing slashes for URLs. Update internal links.
  2. Static files — Pelican's static/ → Bengal's static/ or content/ assets.
  3. Plugins — Pelican plugins don't port. Reimplement or find Bengal equivalents.
  4. RSS/feeds — Bengal generates feeds by default for blog sections.
  5. Search — Bengal supports Lunr search indexes. Configure in theme.