Migration Guides

Move from Hugo, Jekyll, MkDocs, Sphinx, Docusaurus, Mintlify, or Fern without restarting from scratch.

All migrations share the same high-level flow — install Bengal, copy content, convert syntax, update config, then verify withbengal buildand bengal check.

Common Migration Steps

1. Install Bengal —pip install bengal or uv add bengal
2. Create a new site —bengal new site mysite
3. Copy content — transfer markdown files tocontent/
4. Convert syntax — replace platform-specific syntax with Bengal directives
5. Update configuration — convert config files tobengal.toml and config/
6. Test and verify — runbengal build and bengal check

Universal Conversions

Most platforms use similar concepts that map to Bengal directives:

What Stays the Same

• Markdown files — content transfers directly
• YAML frontmatter — compatible format
• Directory structure —content/works similarly
• Static output — all generators produce static HTML

What Changes

• Template syntax — platform template language → Kida
• Component syntax — platform components → Bengal directives
• Configuration — platform config →bengal.toml / config/
• Build process — platform CLI →bengal build

Platform-Specific Guides

Troubleshooting Migrations

Template variables not working?

• Check the template variable mapping in your platform's guide
• Hugo:{{ .Params.x }} → {{ page.metadata.x }}
• Jekyll:{{ page.custom }} → {{ page.metadata.custom }}

Directives not rendering?

• Use triple colons::::{note} not :::note
• Directive names are case-sensitive
• See Directives Reference for the full list

Configuration errors?

• Verifybengal.toml or config/layout
• Runbengal config doctor
• See Configuration Guide

Links broken after migration?

• Runbengal checkto find broken links
• Update relative paths if directory structure changed
• Ensure asset paths use the correct prefix for your theme