From Docusaurus/MDX

Onboarding guide for Docusaurus and MDX users migrating to Bengal

9 min read 1789 words

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

:::note
This is a note
:::

:::tip Pro Tip
This is a tip with a title
:::

:::{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

import 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>

:::{tab-set}
:::{tab} JavaScript
```javascript
console.log("Hello");
```
:::{/tab}
:::{tab} Python
```python
print("Hello")
```
:::{/tab}
:::{/tab-set}

Tip

No imports, no JSX, no React. Just markdown.

Code Blocks

import CodeBlock from '@theme/CodeBlock';

<CodeBlock language="python" title="hello.py" showLineNumbers>
def hello():
    print("Hello!")
</CodeBlock>

```python title="hello.py"
def hello():
    print("Hello!")
```

Cards / Feature Grid

import {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>

:::{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

<details>
  <summary>Click to expand</summary>

  Hidden content here with **markdown** support.
</details>

:::{dropdown} Click to expand
:icon: info

Hidden content here with **markdown** support.
:::

Live Code Editor

```jsx live
function Hello() {
  return <div>Hello World!</div>;
}
`

<!-- Option 1: Use embed directives (recommended) -->
:::{codesandbox} sandbox-id
:title: Interactive Example
:::

<!-- Option 2: Link to external playground -->
[Try it on CodeSandbox](https://codesandbox.io/s/example)

<!-- Option 3: Static code example -->
```jsx
function Hello() {
  return <div>Hello World!</div>;
}
```

Note

Bengal focuses on documentation, not interactive playgrounds. For live code, use built-in embed directives:

:::{codesandbox} sandbox-id
:title: My CodeSandbox Example
:::

:::{stackblitz} project-id
:title: StackBlitz Demo
:::

:::{codepen} user/pen-id
:title: CodePen Example
:::

What You Don't Need Anymore

Docusaurus Requires Bengal
npm install pip install bengal or uv 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
npm start(port 3000) bengal serve(port 5173)

Configuration Comparison

Basic Config

module.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'),
        },
      },
    ],
  ],
};

[site]
title = "My Site"
description = "Documentation made easy"
baseurl = "https://example.com"
theme = "bengal"

module.exports = {
  docs: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      items: ['quickstart', 'installation'],
    },
    {
      type: 'category',
      label: 'Guides',
      items: ['guide1', 'guide2'],
    },
  ],
};

<!-- Bengal auto-generates sidebar from directory structure -->
<!-- Control ordering with weight frontmatter: -->

<!-- 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

Nosidebars.js needed! Bengal automatically generates navigation from your directory structure. Use weight frontmatter to control the order—lower numbers appear first. Pages without weightare sorted alphabetically.

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 tov1/, v2/folders
i18n Plugin langfrontmatter 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)

// ❌ MDX - Won't work in Bengal
import MyComponent from '@site/src/components/MyComponent';

<MyComponent prop="value" />

<!-- ✅ Bengal - Use built-in directives instead -->
:::{card} Title
:link: /path/

Content here
:::

Export/Props Don't Work (Use Frontmatter)

// ❌ MDX - Won't work
export const data = { version: '2.0' };

Current version: {data.version}

<!-- ✅ Bengal - Use frontmatter -->
---
title: My Page
version: "2.0"
---

Current version: {{ page.metadata.version }}

JSX in Markdown → Use Directives or HTML

// ❌ MDX - Won't work
<div className="custom-box">
  <h3>Custom Content</h3>
  <p>With JSX styling</p>
</div>

<!-- ✅ 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 Useweight
package.json pyproject.toml(optional) Dependencies

What Bengal Adds

---
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.

# 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]

<!-- In any page -->
:::{glossary}
:tags: api
:::

<!-- Auto-generate cards from child pages -->
:::{child-cards}
:columns: 3
:::

<!-- Show sibling pages in section -->
:::{siblings}
:::

<!-- Prev/Next navigation links -->
:::{prev-next}
:::

<!-- Breadcrumb navigation -->
:::{breadcrumbs}
:::

<!-- Related pages by tag -->
:::{related}
:tags: api, authentication
:::

:::{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

  • Copydocs/ to content/docs/
  • Copyblog/ to content/blog/
  • Convert:::note to :::{note}(add braces)
  • Remove MDX imports (use built-in directives)
  • Convert React components to directives

Configuration

  • Createbengal.toml from docusaurus.config.js
  • Removesidebars.js (use weightfrontmatter)
  • Movestatic/ to assets/

Cleanup

  • Removenode_modules/
  • Removepackage.json
  • Removesrc/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?

Use Bengal's built-in embed directives:

:::{codesandbox} example-id
:title: Interactive Example
:::

:::{stackblitz} example-id
:title: StackBlitz Demo
:::

Or link directly:

[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 inthemes/[name]/static/css/custom.cssand 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.

If you're migrating from multiple platforms or need additional context:

Next Steps