From Sphinx/RST

Onboarding guide for Sphinx and reStructuredText users migrating to Bengal

8 min read 1555 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}.

Directive Syntax

Bengal uses colon-based syntax only (:::{name}). Backtick syntax (````{name}`) renders as code blocks, not directives. This avoids conflicts when showing directive examples in documentation.

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

Side-by-Side Example

.. note:: Important

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

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

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

:::{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:: :::{since} Semantic versioning directive
.. deprecated:: :::{deprecated} Semantic deprecation notice
.. versionchanged:: :::{changed} Version change notice
.. 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: Literalinclude Usage

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

Cross-References

Bengal uses[[label]]syntax for intelligent cross-references that automatically resolve page titles and paths.

Sphinx Bengal Notes
:ref:\label`` [[path]]or[[path|Custom Text]] Auto-resolves page title
:doc:\path`` [[path]]or standard markdown links Standard markdown also works
:term:\glossary`` :::{glossary}directive Data-driven
.. _label: {#label}in heading MyST anchor syntax

Example: Cross-Reference Examples

<!-- Basic cross-reference (uses page title automatically) -->
[[docs/getting-started]]

<!-- Cross-reference with custom text -->
[[docs/getting-started|Get Started Guide]]

<!-- Link to heading anchor -->
[[#installation]]
[[docs/getting-started#installation]]

<!-- Link by custom ID (if page has id: in frontmatter) -->
[[id:install-guide]]

<!-- Standard markdown links also work -->
[Configuration Guide](../reference/configuration.md)
[Config Options](../reference/configuration.md#options)

Cross-Reference Benefits

[[path]]syntax automatically:

  • Resolves to the correct page URL
  • Uses the page's title as link text (unless you specify custom text)
  • Handles path normalization automatically
  • Provides O(1) lookup performance

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:

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

Example: Minimal bengal.toml

[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}
: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}

:::{tab-set}

:::{tab} pip
```bash
pip install mypackage
```
:::{/tab}

:::{tab} conda
```bash
conda install mypackage
```
:::{/tab}

:::{/tab-set}

:::{steps}

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

:::{step} Create Site
```bash
bengal new site mysite
```
:::{/step}

:::{/steps}

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

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

Bengal supports{{ variable }}substitution directly in markdown content:

---
title: My Page
version: "2.0"
---

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

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

Site name: {{ site.config.title }}

Variables available in content:

  • page.title,page.url,page.date- Page properties
  • page.metadata.xxx- Custom frontmatter fields
  • site.config.xxx- Site configuration values
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) Built-in 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 Built-in support KaTeX rendering

autodoc Alternative

Bengal has a built-in autodoc system that generates API documentation from Python source. Configure it in eitherbengal.tomlorconfig/_default/autodoc.yaml:

[autodoc.python]
enabled = true
source_dirs = ["src/"]
output_prefix = "api"  # Pages appear under /api/

autodoc:
  python:
    enabled: true
    source_dirs: ["src/"]
    output_prefix: "api"  # Pages appear under /api/

This generates virtual pages during the build process, unlike Sphinx's runtime introspection. Runbengal buildto generate API documentation from your Python source.

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}(colon syntax only)
  • Convert:ref:links to[[path]]cross-references or markdown links
  • Update code blocks to fenced syntax (````python`)
  • 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

Common Questions

Can I still use RST files?

Not directly. Bengal uses MyST Markdown, which has similar directive syntax to RST. You'll need to convert.rstfiles to.md, but the concepts transfer directly—.. note::becomes:::{note}, etc.

What about my Sphinx extensions?

Bengal has built-in directives that cover most common extension functionality (tabs, cards, admonitions, literalinclude). For specialized extensions, check if there's a built-in directive equivalent or use custom templates.

Can I use intersphinx for cross-project references?

Not built-in. Use explicit URLs for cross-project links. If you're documenting multiple projects, consider a monorepo structure with all docs in one Bengal site.

What about autodoc for Python API docs?

Bengal has built-in autodoc! Configure it inconfig/_default/autodoc.yamlto generate API documentation from your Python source. It works differently from Sphinx (build-time vs runtime), but achieves similar results.

Next Steps