# From Sphinx/RST URL: /docs/tutorials/onboarding/from-sphinx/ Section: onboarding Tags: tutorial, migration, sphinx, rst, myst -------------------------------------------------------------------------------- Bengal for Sphinx/RST Users 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 Sphinx (RST) Bengal (MyST) 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 from weight File-system based :maxdepth: 2 Sidebar depth in theme config Theme setting :caption: Guide Section titles in _index.md Content structure :hidden: hidden: true frontmatter Per-page Bengal auto-generates navigation from your directory structure. Use weight frontmatter 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/ Minimal bengal.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} 1Create Sitebengal 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 3bengal 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 in bengal.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 Add weight frontmatter for ordering Configuration Migration Create bengal.toml from conf.py settings Move _static/ to assets/ 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 Writer Quickstart - Full markdown reference Directives Reference - All available directives Configuration - Full config options -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 842 - Reading Time: 4 minutes