Migration Guides

Step-by-step guides to migrate your site from another static site generator to Bengal.

Migration Overview

All migrations follow similar patterns, regardless of your source platform:

Common Migration Steps

1. Install Bengal:pip install bengal or uv add bengal
2. Create new site:bengal new site mysite
3. Copy content: Transfer your markdown files tocontent/
4. Convert syntax: Replace platform-specific syntax with Bengal directives
5. Update configuration: Convert config files tobengal.toml
6. Test and verify: Runbengal build and bengal health linkcheck

Universal Conversions

Most platforms use similar concepts that map to Bengal directives:

What Stays the Same

• Markdown files: Your content files transfer directly
• YAML frontmatter: Frontmatter format is compatible
• Directory structure:content/structure works similarly
• Static output: All generators produce static HTML

What Changes

• Template syntax: Each platform's template language → Jinja2
• Component syntax: Platform-specific components → Bengal directives
• Configuration: Platform config →bengal.toml
• Build process: Platform CLI →bengal build

Common Issues

Template variables not working?

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

Directives not rendering?

• Ensure you're using triple colons::::{note} not :::note
• Check that directive names match exactly (case-sensitive)
• See the Directives Reference for all available directives

Configuration errors?

• Verifybengal.tomlsyntax (TOML format)
• Check that all required[site]fields are present
• See the Configuration Reference for details

Links broken after migration?

• Runbengal health linkcheckto find broken links
• Update relative paths if directory structure changed
• Check that asset paths use/assets/prefix

Platform-Specific Guides