# From Docusaurus/MDX URL: /docs/tutorials/onboarding/from-docusaurus/ Section: onboarding Tags: tutorial, migration, docusaurus, mdx, react -------------------------------------------------------------------------------- Bengal for Docusaurus/MDX Users Great news: You get the same rich components without React, JSX, or npm. Bengal's directives provide similar functionality in pure Markdown. Quick Wins (5 Minutes) Admonition Syntax Is Almost Identical Docusaurus Bengal Status :::note :::{note} ✅ Just add {} :::tip :::{tip} ✅ Just add {} :::warning :::{warning} ✅ Just add {} :::danger :::{danger} ✅ Just add {} :::info :::{info} ✅ Just add {} Side-by-Side Docusaurus Bengal 1 2 3 4 5 6 7:::note This is a note ::: :::tip Pro Tip This is a tip with a title ::: 1 2 3 4 5 6 7:::{note} This is a note ::: :::{tip} Pro Tip This is a tip with a title ::: The only difference: :::note → :::{note} (add curly braces). Component → Directive Translation Tabs Docusaurus (MDX) Bengal (No imports!) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; <Tabs> <TabItem value="js" label="JavaScript"> ```javascript console.log("Hello"); ``` </TabItem> <TabItem value="py" label="Python"> ```python print("Hello") ``` </TabItem> </Tabs> 1 2 3 4 5 6 7 8 9 10 11 12:::{tab-set} :::{tab} JavaScript ```javascript console.log("Hello"); ``` :::{/tab} :::{tab} Python ```python print("Hello") ``` :::{/tab} :::{/tab-set} Tip Tip No imports, no JSX, no React. Just markdown. Code Blocks Docusaurus Bengal 1 2 3 4 5 6import CodeBlock from '@theme/CodeBlock'; <CodeBlock language="python" title="hello.py" showLineNumbers> def hello(): print("Hello!") </CodeBlock> 1 2 3 4```python title="hello.py" def hello(): print("Hello!") ``` Cards / Feature Grid Docusaurus (Custom Component) Bengal (Built-in!) 1 2 3 4 5 6 7 8 9 10import {Card, CardGrid} from '@site/src/components/Card'; <CardGrid> <Card title="Quick Start" href="/docs/quickstart"> Get started in 5 minutes </Card> <Card title="API Reference" href="/docs/api"> Complete API documentation </Card> </CardGrid> 1 2 3 4 5 6 7 8 9 10 11:::{cards} :columns: 2 :::{card} Quick Start :link: /docs/quickstart/ Get started in 5 minutes :::{/card} :::{card} API Reference :link: /docs/api/ Complete API documentation :::{/card} :::{/cards} Collapsible Sections Docusaurus Bengal 1 2 3 4 5<details> <summary>Click to expand</summary> Hidden content here with **markdown** support. </details> 1 2 3 4 5:::{dropdown} Click to expand :icon: info Hidden content here with **markdown** support. ::: Live Code Editor Docusaurus Bengal 1 2 3 4```jsx live function Hello() { return <div>Hello World!</div>; } 1 2 3 4 5 6 7 8 9 10<!-- Live editors not built-in --> <!-- Options: --> <!-- 1. Link to CodeSandbox/StackBlitz --> <!-- 2. Embed external playground --> <!-- 3. Use static code examples --> ```jsx function Hello() { return <div>Hello World!</div>; } Note Note Bengal focuses on documentation, not interactive playgrounds. For live code, link to external tools like CodeSandbox, StackBlitz, or Jupyter. What You Don't Need Anymore Docusaurus Requires Bengal npm install pip install bengal node_modules/ (500MB+) ~5MB Python package React/JSX knowledge Just Markdown Component imports Built-in directives package.json bengal.toml Build step (Webpack) Simple file processing Hydration debugging Static HTML Configuration Comparison Basic Config Docusaurus (docusaurus.config.js) Bengal (bengal.toml) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20module.exports = { title: 'My Site', tagline: 'Documentation made easy', url: 'https://example.com', baseUrl: '/', presets: [ [ '@docusaurus/preset-classic', { docs: { sidebarPath: require.resolve('./sidebars.js'), }, theme: { customCss: require.resolve('./src/css/custom.css'), }, }, ], ], }; 1 2 3 4 5[site] title = "My Site" description = "Documentation made easy" baseurl = "https://example.com" theme = "bengal" Sidebar Configuration Docusaurus (sidebars.js) Bengal (Automatic!) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15module.exports = { docs: [ 'intro', { type: 'category', label: 'Getting Started', items: ['quickstart', 'installation'], }, { type: 'category', label: 'Guides', items: ['guide1', 'guide2'], }, ], }; 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20<!-- Bengal auto-generates sidebar from directory structure --> <!-- Use weight frontmatter for ordering: --> <!-- content/docs/getting-started/_index.md --> --- title: Getting Started weight: 10 --- <!-- content/docs/getting-started/quickstart.md --> --- title: Quickstart weight: 10 --- <!-- content/docs/getting-started/installation.md --> --- title: Installation weight: 20 --- Tip Tip No sidebars.js needed! Bengal generates navigation from your directory structure. Use weight frontmatter to control order. Feature Comparison What Bengal Has (No React Required) Feature Docusaurus Bengal Admonitions :::note :::{note} ✅ Tabs <Tabs> component :::{tab-set} ✅ Code blocks Built-in Built-in ✅ Cards Custom component :::{cards} ✅ Dropdowns <details> :::{dropdown} ✅ Steps Custom component :::{steps} ✅ Badges Custom component :::{badge} ✅ Buttons Custom component :::{button} ✅ Include files MDX import :::{include} ✅ Code inclusion MDX import :::{literalinclude} ✅ TOC Built-in Built-in ✅ Search Algolia Built-in index Breadcrumbs Theme :::{breadcrumbs} ✅ Prev/Next Built-in :::{prev-next} ✅ What's Different (Trade-offs) Feature Docusaurus Bengal Trade-off Live code Built-in External links Simpler, no hydration Versioning Plugin Manual Copy to v1/, v2/ folders i18n Plugin lang frontmatter Simpler, less automated Algolia Integrated External Bring your own search Custom components React/JSX Templates Less flexible, more standard Plugins npm ecosystem Built-in directives Fewer options, zero config MDX-Specific Migration Imports Don't Work (You Don't Need Them) 1 2 3 4// ❌ MDX - Won't work in Bengal import MyComponent from '@site/src/components/MyComponent'; <MyComponent prop="value" /> 1 2 3 4 5 6<!-- ✅ Bengal - Use built-in directives instead --> :::{card} Title :link: /path/ Content here ::: Export/Props Don't Work (Use Frontmatter) 1 2 3 4// ❌ MDX - Won't work export const data = { version: '2.0' }; Current version: {data.version} 1 2 3 4 5 6 7<!-- ✅ Bengal - Use frontmatter --> --- title: My Page version: "2.0" --- Current version: {{ page.metadata.version }} JSX in Markdown → Use Directives or HTML 1 2 3 4 5// ❌ MDX - Won't work <div className="custom-box"> <h3>Custom Content</h3> <p>With JSX styling</p> </div> 1 2 3 4 5 6 7 8 9 10 11 12<!-- ✅ Bengal - Use directive or HTML --> :::{card} Custom Content :class: custom-box With directive styling ::: <!-- Or plain HTML (still works) --> <div class="custom-box"> <h3>Custom Content</h3> <p>With HTML styling</p> </div> Directory Structure Comparison Docusaurus Bengal Notes docs/ content/docs/ Content location blog/ content/blog/ Blog posts src/pages/ content/ Static pages src/components/ Not needed Use directives src/css/ themes/[name]/static/css/ Custom CSS static/ assets/ Static files docusaurus.config.js bengal.toml Configuration sidebars.js Auto-generated Use weight package.json pyproject.toml (optional) Dependencies What Bengal Adds Variable Substitution in Content 1 2 3 4 5 6 7 8 9 10 11--- title: API Reference api_version: "3.0" base_url: "https://api.example.com" --- # {{ page.title }} Current API version: **{{ page.metadata.api_version }}** Base URL: `{{ page.metadata.base_url }}` Docusaurus requires React state or MDX exports for this. Centralized Glossary 1 2 3 4 5 6 7 8 9# data/glossary.yaml terms: - term: API definition: Application Programming Interface tags: [api, core] - term: Endpoint definition: A specific URL path that accepts requests tags: [api, http] 1 2 3 4<!-- In any page --> :::{glossary} :tags: api ::: Navigation Directives 1 2 3 4 5 6 7 8 9 10 11 12 13<!-- Auto-generate cards from child pages --> :::{child-cards} :columns: 3 ::: <!-- Show sibling pages in section --> :::{siblings} ::: <!-- Related pages by tag --> :::{related} :tags: api, authentication ::: Data Tables 1 2 3 4 5 6:::{data-table} :source: data/endpoints.yaml :columns: method, path, description :sortable: true :filterable: true ::: Migration Checklist Before You Start Install Bengal: pip install bengal Create new site: bengal new site mysite Keep Docusaurus running for reference Content Migration Copy docs/ to content/docs/ Copy blog/ to content/blog/ Convert :::note to :::{note} (add braces) Remove MDX imports (use built-in directives) Convert React components to directives Configuration Create bengal.toml from docusaurus.config.js Remove sidebars.js (use weight frontmatter) Move static/ to assets/ Cleanup Remove node_modules/ Remove package.json Remove src/ directory Verify Build: bengal build Check: bengal health linkcheck Preview: bengal serve Quick Reference Card Task Docusaurus Bengal Install npm install pip install bengal New site npx create-docusaurus bengal new site Build npm run build bengal build Serve npm start bengal serve Note :::note :::{note} Tabs <Tabs> + import :::{tab-set} Cards Custom component :::{cards} Dropdown <details> :::{dropdown} Include MDX import :::{include} Common Questions "Can I use React components?" No. Bengal outputs static HTML. For interactivity: Use vanilla JavaScript Embed external widgets (CodeSandbox, etc.) Link to interactive demos "What about live code playgrounds?" Link to external tools: 1 2[Try it on CodeSandbox](https://codesandbox.io/s/example) [Open in StackBlitz](https://stackblitz.com/edit/example) "Can I keep my custom CSS?" Yes! Put it in themes/[name]/static/css/custom.css and include in your template. "What about search?" Bengal generates a search index. For Algolia-level search, integrate externally or use the built-in index with JavaScript. Next Steps Directives Reference - All available directives Writer Quickstart - Full markdown guide Configuration - Config options -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1411 - Reading Time: 7 minutes