# Migration Guides

URL: /docs/tutorials/migration/
Section: migration

--------------------------------------------------------------------------------

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 Install Bengal: pip install bengal or uv add bengal Create new site: bengal new site mysite Copy content: Transfer your markdown files to content/ Convert syntax: Replace platform-specific syntax with Bengal directives Update configuration: Convert config files to bengal.toml Test and verify: Run bengal build and bengal 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 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? Verify bengal.toml syntax (TOML format) Check that all required [site] fields are present See the Configuration Reference for details Links broken after migration? Run bengal health linkcheck to 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

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 367
- Reading Time: 2 minutes