Migration Guides

Migrate to Bengal from other static site generators

2 min read 480 words

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 bengaloruv 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 buildandbengal health linkcheck

Universal Conversions

Most platforms use similar concepts that map to Bengal directives:

Source Syntax Bengal Directive Common Use Case
Shortcodes/Components :::{directive} Callouts, tabs, cards
Code highlighting ```lang Code blocks
Includes :::{include} Reusable content
Frontmatter YAML frontmatter Page metadata

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

Tip

Not sure which guide to follow? Choose the guide for your current platform. If you're migrating from multiple platforms or a custom setup, start with the guide closest to your syntax (e.g., Hugo for shortcodes, Docusaurus for MDX components).

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

From Hugo
Hugo to Bengal migration
From Jekyll
Jekyll to Bengal migration
From MkDocs
MkDocs to Bengal migration
From Sphinx
Sphinx to Bengal migration
From Docusaurus
Docusaurus to Bengal migration
From Mintlify
Mintlify to Bengal migration
From Fern
Fern to Bengal migration