From Jekyll

Moving from Ruby to Python? Bengal simplifies your stack while keeping the content-first approach you know.

Quick Wins (5 Minutes)

What Works The Same

The Key Difference

Liquid templates → Bengal directives:

<!-- Jekyll (Liquid) -->
{% highlight python %}
print("Hello")
{% endhighlight %}

<!-- Bengal -->
```python
print("Hello")
```

No more {% %}tags in your content.

Liquid → Markdown Translation

Code Blocks

{% highlight python linenos %}
def hello():
    print("Hello!")
{% endhighlight %}

```python
def hello():
    print("Hello!")
```

Including Files

{% include note.html content="This is a note." %}

{% include_relative ../snippets/example.md %}

:::{note}
This is a note.
:::

:::{include} ../snippets/example.md
:::

Callouts / Alerts

Jekyll doesn't have built-in callouts (you use includes or custom CSS). Bengal has them built-in:

:::{note}
This is a note.
:::

:::{warning}
Be careful!
:::

:::{tip}
Pro tip here.
:::

:::{danger}
Critical warning!
:::

Links and References

<!-- Post URL -->
[Read more]({{ site.baseurl }}{% post_url 2024-01-15-my-post %})

<!-- Page link -->
[About]({{ "/about/" | relative_url }})

<!-- Asset -->
![Logo]({{ "/assets/logo.png" | relative_url }})

<!-- Post URL -->
[Read more](/blog/2024-01-15-my-post/)

<!-- Page link -->
[About](/about/)

<!-- Asset -->
![Logo](/images/logo.png)

Frontmatter Mapping

Post/Page Frontmatter

---
layout: post
title: "My Blog Post"
date: 2024-01-15 10:30:00 -0500
categories: [python, tutorial]
tags: [beginner, tips]
author: jane
excerpt: "A brief introduction..."
published: true
---

---
title: "My Blog Post"
date: 2024-01-15
category: python
tags: [tutorial, beginner, tips]
author: jane
description: "A brief introduction..."
draft: false
---

Key Differences

Configuration Mapping

Basic Site Config

title: My Site
description: A great site
baseurl: ""
url: "https://example.com"

# Build settings
markdown: kramdown
theme: minima
plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-sitemap

# Collections
collections:
  docs:
    output: true
    permalink: /docs/:path/

[site]
title = "My Site"
description = "A great site"
baseurl = "https://example.com"
theme = "bengal"

# Feed, SEO, sitemap are built-in
# No plugins needed

# Collections auto-detected from content/

No Plugin Configuration

Jekyll features that require plugins are built into Bengal:

Directory Structure Comparison

Template Variable Mapping

Page Variables

Site Variables

Template Logic

What Bengal Adds (Jekyll Doesn't Have)

:::{note}
Built-in callout boxes.
:::

:::{warning}
No plugins or includes needed.
:::

:::{tip}
Multiple types available.
:::

:::{tab-set}
:::{tab} Ruby
```ruby
puts "Hello"
```
:::{/tab}
:::{tab} Python
```python
print("Hello")
```
:::{/tab}
:::{/tab-set}

:::{cards}
:columns: 2

:::{card} Feature 1
:icon: rocket

Description here
:::{/card}

:::{card} Feature 2
:icon: star

Another feature
:::{/card}

:::{/cards}

:::{steps}

:::{step} Clone Repository
```bash
git clone https://github.com/user/repo.git
```
:::{/step}

:::{step} Install Dependencies
```bash
pip install -r requirements.txt
```
:::{/step}

:::{/steps}

bengal serve
# Hot reload at http://localhost:5173
# Instant updates on save

What's Different (Honest Gaps)

GitHub Pages Deployment

Jekyll has native GitHub Pages support. With Bengal, use GitHub Actions:

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.14'  # Or '3.14t' for free-threading build
      - run: pip install bengal
      - run: bengal build
      # Pin to SHA for supply chain security (v3.9.3)
      - uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Migration Steps

Migration Checklist

Quick Reference Card

Common Questions

Related Migration Guides

If you're migrating from multiple platforms or need additional context:

• From Hugo - Similar template-to-directive conversion patterns
• Migration Overview - Common migration patterns across all platforms

Next Steps

• Writer Quickstart - Full markdown reference
• Directives Reference - All available directives
• Configuration Reference - Full config options
• Cheatsheet - Quick syntax reference