From Sphinx/RST

Onboarding guide for Sphinx and reStructuredText users migrating to Bengal

6 min read 1151 words

You're 80% there. Bengal uses MyST-compatible syntax that mirrors what you already know.

Quick Wins (5 Minutes)

Your Directives Work (Almost)

The only syntax change:.. name::becomes:::{name}.

Sphinx/RST Bengal Works?
.. note:: :::{note} ✅
.. warning:: :::{warning} ✅
.. tip:: :::{tip} ✅
.. danger:: :::{danger} ✅
.. literalinclude:: :::{literalinclude} ✅
.. include:: :::{include} ✅

Side-by-Side Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.. note:: Important

   This is a note with **bold** text.

.. code-block:: python
   :linenos:
   :emphasize-lines: 2

   def hello():
       print("Hello, World!")

1
2
3
4
5
6
7
8
:::{note} Important
This is a note with **bold** text.
:::

```python
def hello():
    print("Hello, World!")
```

Complete Feature Mapping

Admonitions

Sphinx Bengal Notes
.. note:: :::{note} Identical semantics
.. warning:: :::{warning} Identical semantics
.. tip:: :::{tip} Identical semantics
.. danger:: :::{danger} Identical semantics
.. seealso:: :::{seealso} Supported
.. versionadded:: Use:::{info} Manual text
.. deprecated:: Use:::{warning} Manual text
.. admonition:: Custom :::{note} Custom Title Title in directive

Code Blocks

Sphinx Bengal Notes
.. code-block:: python ```python Standard fenced
:linenos: Not built-in CSS-based line numbers
:emphasize-lines: Not built-in Use comments to highlight
.. highlight:: python Not needed Each block specifies language

File Inclusion

Sphinx Bengal Notes
.. literalinclude:: file.py :::{literalinclude} file.py ✅ Same
:lines: 1-10 :lines: 1-10 ✅ Same option
:language: python :language: python ✅ Same option
.. include:: file.md :::{include} file.md ✅ Same

Example

1
2
3
4
5
:::{literalinclude} ../examples/hello.py
:language: python
:lines: 5-15
:caption: Hello World Example
:::

Cross-References

Sphinx Bengal Notes
:ref:\label`` [[label]]or[text](./file.md) Different syntax
:doc:\path`` [text](./file.md) Standard markdown
:term:\glossary`` :::{glossary}directive Data-driven
.. _label: {#label}in heading MyST anchor syntax

Cross-reference examples:

1
2
3
4
5
6
7
8
<!-- Link to another page -->
[Configuration Guide](../reference/configuration.md)

<!-- Link with anchor -->
[Config Options](../reference/configuration.md#options)

<!-- Internal cross-reference -->
[[installation]]

Table of Contents

Sphinx Bengal Notes
.. toctree:: Auto-generated fromweight File-system based
:maxdepth: 2 Sidebar depth in theme config Theme setting
:caption: Guide Section titles in_index.md Content structure
:hidden: hidden: truefrontmatter Per-page

Bengal auto-generates navigation from your directory structure. Useweightfrontmatter to control order:

1
2
3
4
---
title: Installation
weight: 10  # Lower = appears first
---

Configuration

Sphinx (conf.py) Bengal (bengal.toml)
project = 'My Docs' [site]
title = "My Docs"
extensions = [...] Built-in (no extensions needed)
html_theme = 'sphinx_rtd_theme' [site]
theme = "bengal"
html_static_path = ['_static'] assets/directory
templates_path = ['_templates'] themes/[name]/templates/

Minimalbengal.toml:

1
2
3
4
5
[site]
title = "My Documentation"
baseurl = "https://docs.example.com"
language = "en"
theme = "bengal"

Directory Structure

Sphinx Bengal Notes
source/ content/ Content root
_static/ assets/ Static files
_templates/ themes/[name]/templates/ Template overrides
conf.py bengal.toml Configuration
index.rst _index.md Section index
Makefile bengal build Build command

What Bengal Adds (Sphinx Doesn't Have)

Cards for Feature Grids

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
:::{cards}
:columns: 3

:::{card} Quick Start
:icon: 🚀
:link: quickstart

Get started in 5 minutes
:::

:::{card} API Reference
:icon: 📚
:link: api/

Complete API docs
:::

:::{/cards}

Tab Sets

1
2
3
4
5
:::{tab-set}

:::{tab-item} pip
```bash
pip install mypackage

:::

conda install mypackage

:::{/tab-set}


### Visual Steps

```markdown
:::{steps}

:::{step} Install Dependencies
```bash
pip install bengal

:::{/step}

  • 1

    Create Site

    bengal new site mysite

    • :::{/steps}

    
### Dropdowns (Collapsible Sections)

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

Hidden content here. Supports **full markdown**.
:::

    Variable Substitution in Content

    1
2
3
4
5
6
7
8
    ---
title: My Page
version: "2.0"
---

# Welcome to version {{ page.metadata.version }}

The current page is: {{ page.title }}

    Hot Reload Development Server

    1
2
3
    bengal serve
# Live preview at http://localhost:5173
# Auto-reloads on file changes

    What's Different (Honest Gaps)

    Sphinx Feature Bengal Status Workaround
    autodoc(Python introspection) Config-driven Configure inbengal.toml
    intersphinx(cross-project refs) Not built-in Use explicit URLs
    Custom builders (PDF, ePub) HTML only External tools
    Domain-specific roles Not built-in Use directives
    Numbered figures Manual numbering CSS counters
    Math/LaTeX Extension needed KaTeX CSS/JS

    autodoc Alternative

    Bengal has a separate autodoc system:

    1
2
3
4
    # Configure autodoc in bengal.toml
[autodoc.python]
enabled = true
source_dirs = ["src/"]

    This creates markdown files you can customize, unlike Sphinx's runtime introspection.

    Migration Checklist

    Before You Start

    • Install Bengal:pip install bengal
    • Create new site:bengal new site mysite
    • Copy content files (.rst→.md)

    Content Migration

    • Convert.. directive::to:::{directive}
    • Convert:ref:links to markdown link syntax
    • Update code blocks to fenced syntax
    • Addweightfrontmatter for ordering

    Configuration Migration

    • Createbengal.tomlfromconf.pysettings
    • Move_static/toassets/
    • Move_templates/to theme templates

    Verify

    • Build:bengal build
    • Check links:bengal health linkcheck
    • Preview:bengal serve

    Quick Reference Card

    Task Sphinx Bengal
    Create note .. note:: :::{note}
    Create warning .. warning:: :::{warning}
    Include file .. include:: :::{include}
    Include code .. literalinclude:: :::{literalinclude}
    Cross-reference :ref:\label`` [[label]]
    Link to doc :doc:\path`` Standard markdown links
    Build make html bengal build
    Serve sphinx-autobuild bengal serve
    Check sphinx-build -W bengal health linkcheck

    Next Steps