# From MkDocs URL: /docs/tutorials/migration/from-mkdocs/ Section: migration Tags: tutorial, migration, mkdocs, material -------------------------------------------------------------------------------- Bengal for MkDocs Users You're in familiar territory. Both tools are Python-native and use Markdown. The main change: MkDocs extensions become Bengal directives. Quick Wins (5 Minutes) What Works The Same MkDocs Bengal Status docs/ structure content/ ✅ Similar Markdown files Markdown files ✅ Identical YAML frontmatter YAML frontmatter ✅ Identical mkdocs.yml bengal.toml ✅ Similar pip install pip install ✅ Same ecosystem The Key Difference MkDocs extensions → Bengal directives: <!-- MkDocs (with admonition extension) --> !!! note "Title" This is a note <!-- Bengal --> :::{note} Title This is a note ::: Extension → Directive Translation Admonitions MkDocs Bengal !!! note This is a note. !!! warning "Be Careful" This is a warning with a custom title. !!! tip A helpful tip. !!! danger Critical warning! ??? note "Collapsible" This content is hidden by default. :::{note} This is a note. ::: :::{warning} Be Careful This is a warning with a custom title. ::: :::{tip} A helpful tip. ::: :::{danger} Critical warning! ::: :::{dropdown} Collapsible :icon: note This content is hidden by default. ::: Admonition Types Mapping MkDocs Bengal Notes !!! note :::{note} ✅ Same !!! warning :::{warning} ✅ Same !!! tip :::{tip} ✅ Same !!! danger :::{danger} ✅ Same !!! info :::{info} ✅ Same !!! example :::{example} ✅ Same !!! quote :::{epigraph} Different name !!! bug :::{danger} Use danger !!! abstract :::{note} Use note ??? note (collapsible) :::{dropdown} Different syntax ???+ note (open) :::{dropdown} + :open: Different syntax Tabs (with pymdownx.tabbed) MkDocs Bengal === "Python" ```python print("Hello") ``` === "JavaScript" ```javascript console.log("Hello"); ``` :::{tab-set} :::{tab} Python ```python print("Hello") ``` :::{/tab} :::{tab} JavaScript ```javascript console.log("Hello"); ``` :::{/tab} :::{/tab-set} Code Blocks MkDocs Bengal ```python title="hello.py" linenums="1" hl_lines="2" def hello(): print("Hello!") # highlighted return True ``` ```python # hello.py def hello(): print("Hello!") # use comments for emphasis return True ``` Content Tabs with Code MkDocs Bengal === "pip" ```bash pip install mypackage ``` === "conda" ```bash conda install mypackage ``` === "uv" ```bash uv add mypackage ``` :::{tab-set} :::{tab} pip ```bash pip install mypackage ``` :::{/tab} :::{tab} conda ```bash conda install mypackage ``` :::{/tab} :::{tab} uv ```bash uv add mypackage ``` :::{/tab} :::{/tab-set} Configuration Mapping Basic Site Config MkDocs (mkdocs.yml) Bengal (bengal.toml) site_name: My Documentation site_url: https://docs.example.com site_description: My awesome docs theme: name: material palette: primary: indigo accent: indigo nav: - Home: index.md - Guide: - Getting Started: guide/getting-started.md - Installation: guide/installation.md [site] title = "My Documentation" baseurl = "https://docs.example.com" description = "My awesome docs" theme = "bengal" # Navigation is auto-generated from directory structure # Use weight frontmatter to control order Navigation MkDocs requires explicit nav configuration in mkdocs.yml. Bengal auto-generates navigation from your directory structure using weight frontmatter: --- title: Getting Started weight: 10 # Lower = appears first --- Tip Tip This is a major simplification. Add a page, and it appears in nav automatically. No config file edits needed. Extensions → Built-in MkDocs Extension Bengal Notes admonition Built-in :::{note}, :::{warning}, etc. pymdownx.tabbed Built-in :::{tab-set} pymdownx.details Built-in :::{dropdown} pymdownx.superfences Built-in Fenced code blocks pymdownx.highlight Built-in Syntax highlighting pymdownx.inlinehilite Built-in Inline code highlighting toc Built-in Auto-generated TOC tables Built-in Standard markdown tables attr_list Limited Use directive options def_list Built-in Standard markdown footnotes Built-in Standard markdown meta Built-in YAML frontmatter pymdownx.emoji Not built-in Use unicode emoji pymdownx.arithmatex Built-in KaTeX math support Directory Structure Comparison MkDocs Bengal Notes docs/ content/ Content root docs/index.md content/_index.md Home page docs/assets/ assets/ Static files mkdocs.yml bengal.toml Configuration overrides/ themes/[name]/templates/ Template overrides custom_theme/ themes/[name]/ Custom themes What Bengal Adds (MkDocs Doesn't Have Built-in) Cards Grid Visual Steps Data Tables Variables in Content Built-in Autodoc :::{cards} :columns: 3 :::{card} Quick Start :icon: rocket :link: quickstart Get started in 5 minutes :::{/card} :::{card} API Reference :icon: book :link: api/ Complete API docs :::{/card} :::{/cards} :::{steps} :::{step} Install Dependencies ```bash pip install bengal ``` :::{/step} :::{step} Create Site ```bash bengal new site mysite ``` :::{/step} :::{step} Start Server ```bash bengal serve ``` :::{/step} :::{/steps} :::{data-table} :source: data/products.yaml :columns: name, price, stock :sortable: true :filterable: true ::: Bengal supports {{ variable }} substitution directly in markdown: --- title: Release Notes version: "2.5.0" --- # {{ page.title }} Current version: **{{ page.metadata.version }}** Site: {{ site.config.title }} # config/_default/autodoc.yaml autodoc: python: enabled: true source_dirs: ["src/"] output_prefix: "api" No external plugins needed for Python API docs. What's Different (Honest Gaps) MkDocs Feature Bengal Status Workaround Material theme features Different theme Bengal has its own theme mkdocs-material insiders Not applicable Use Bengal's built-in features Explicit nav ordering Auto from weight Add frontmatter Plugin ecosystem Built-in features Most common plugins built-in mkdocstrings Built-in autodoc Different configuration Search (Lunr.js) Built-in search Similar functionality Social cards Not built-in Use external tools Blog plugin Built-in blog Different configuration Material for MkDocs Specific If you're using Material for MkDocs, here's what to expect: Material Feature Bengal Equivalent Instant loading Not built-in (static HTML) Dark/light toggle Built-in theme toggle Search suggestions Built-in search Content tabs :::{tab-set} Annotations Use :::{note} Icons/emojis Built-in icons (Phosphor) Code copy button Built-in Navigation tabs Theme configuration Back to top Built-in Migration Steps 1Install Bengalpip install bengal # or with uv uv add bengal 2Create New Sitebengal new site mysite cd mysite 3Copy Content# Copy your MkDocs content cp -r /path/to/mkdocs/docs/* content/ # Rename index.md to _index.md for sections find content -name "index.md" -exec sh -c 'mv "$1" "$(dirname "$1")/_index.md"' _ {} \; 4Convert AdmonitionsSearch for !!! and convert to directives: # Find all admonition usages grep -r "!!!" content/ Find Replace With !!! note :::{note} !!! warning :::{warning} !!! tip :::{tip} ??? note :::{dropdown} 5Convert TabsReplace === "Tab Name" syntax with Bengal's tab directives. Tabs must be wrapped in :::{tab-set}: MkDocs: === "Python" ```python print("Hello") ``` === "JavaScript" ```javascript console.log("Hello"); ``` Bengal: :::{tab-set} :::{tab} Python ```python print("Hello") ``` :::{/tab} :::{tab} JavaScript ```javascript console.log("Hello"); ``` :::{/tab} :::{/tab-set} 6Add Weight FrontmatterAdd ordering to pages: --- title: Getting Started weight: 10 --- 7Update ConfigCreate bengal.toml based on your mkdocs.yml: [site] title = "My Documentation" baseurl = "https://docs.example.com" theme = "bengal" 8Testbengal build bengal health linkcheck bengal serve Migration Checklist Before You Start Install Bengal: pip install bengal Backup your MkDocs site Create new Bengal site: bengal new site mysite Content Migration Copy docs/ to content/ Rename index.md to _index.md for sections Convert !!! note to :::{note} Convert === "Tab" to :::{tab} syntax Add weight frontmatter for ordering Assets Migration Copy docs/assets/ to assets/ Update asset paths if needed Config Migration Create bengal.toml from mkdocs.yml Remove extension references (built-in) Update theme settings Verify Build: bengal build Check: bengal health linkcheck Preview: bengal serve Quick Reference Card Task MkDocs Bengal New site mkdocs new bengal new site Build mkdocs build bengal build Serve mkdocs serve bengal serve Note !!! note :::{note} Warning !!! warning :::{warning} Collapsible ??? note :::{dropdown} Tabs === "Tab" :::{tab} Tab Config mkdocs.yml bengal.toml Common Questions Question Can I keep my Material theme? No. Bengal has its own theme designed for technical documentation. Many Material features have Bengal equivalents (dark mode, search, code copy, tabs), but the visual design is different. Question What about mkdocstrings for API docs? Bengal has built-in autodoc that generates Python API documentation. Configure it in config/_default/autodoc.yaml. It works at build time, scanning your source code directly. Question Can I use MkDocs plugins? MkDocs plugins are not compatible. However, most popular plugin functionality is built into Bengal: search, tags, blog, API docs, diagrams (Mermaid), math (KaTeX). Check the directives reference for equivalents. Question What about the explicit nav in mkdocs.yml? Bengal auto-generates navigation from your directory structure. Use weight frontmatter to control order and hidden: true to exclude pages. This is simpler once you're used to it—no config file updates when adding pages. Next Steps Writer Quickstart - Full markdown reference Directives Reference - All available directives Configuration Reference - Full config options Cheatsheet - Quick syntax reference -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1285 - Reading Time: 6 minutes