Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Add documentation for sidebar and developer panel (#7758)

Trevor Manz9bcb4ffc9139
diff --git a/docs/_static/docs-dataflow-dependencies-panel.jpg b/docs/_static/docs-dataflow-dependencies-panel.jpg
new file mode 100644
index 0000000000..e9060cf9c4
Binary files /dev/null and b/docs/_static/docs-dataflow-dependencies-panel.jpg differ
diff --git a/docs/_static/docs-dataflow-dependencies-panel.webp b/docs/_static/docs-dataflow-dependencies-panel.webp
new file mode 100644
index 0000000000..9515d7a474
Binary files /dev/null and b/docs/_static/docs-dataflow-dependencies-panel.webp differ
diff --git a/docs/_static/docs-dataflow-graph.jpg b/docs/_static/docs-dataflow-graph.jpg
new file mode 100644
index 0000000000..2c30d933c4
Binary files /dev/null and b/docs/_static/docs-dataflow-graph.jpg differ
diff --git a/docs/_static/docs-dataflow-graph.webp b/docs/_static/docs-dataflow-graph.webp
new file mode 100644
index 0000000000..659990c8eb
Binary files /dev/null and b/docs/_static/docs-dataflow-graph.webp differ
diff --git a/docs/_static/docs-dataflow-minimap.webm b/docs/_static/docs-dataflow-minimap.webm
new file mode 100644
index 0000000000..5e56361c06
Binary files /dev/null and b/docs/_static/docs-dataflow-minimap.webm differ
diff --git a/docs/_static/docs-dataflow-variables-explorer.jpg b/docs/_static/docs-dataflow-variables-explorer.jpg
new file mode 100644
index 0000000000..e2d964e17a
Binary files /dev/null and b/docs/_static/docs-dataflow-variables-explorer.jpg differ
diff --git a/docs/_static/docs-dataflow-variables-explorer.webp b/docs/_static/docs-dataflow-variables-explorer.webp
new file mode 100644
index 0000000000..978f1e707b
Binary files /dev/null and b/docs/_static/docs-dataflow-variables-explorer.webp differ
diff --git a/docs/_static/docs-dependency-explorer.jpg b/docs/_static/docs-dependency-explorer.jpg
deleted file mode 100644
index e79fd96f98..0000000000
Binary files a/docs/_static/docs-dependency-explorer.jpg and /dev/null differ
diff --git a/docs/_static/docs-dependency-explorer.webp b/docs/_static/docs-dependency-explorer.webp
deleted file mode 100644
index 6ec7a055c4..0000000000
Binary files a/docs/_static/docs-dependency-explorer.webp and /dev/null differ
diff --git a/docs/_static/docs-minimap.mp4 b/docs/_static/docs-minimap.mp4
deleted file mode 100644
index a5e6ac02e7..0000000000
Binary files a/docs/_static/docs-minimap.mp4 and /dev/null differ
diff --git a/docs/_static/docs-minimap.webm b/docs/_static/docs-minimap.webm
deleted file mode 100644
index 9f091e3281..0000000000
Binary files a/docs/_static/docs-minimap.webm and /dev/null differ
diff --git a/docs/_static/docs-panel-drag-drop.webm b/docs/_static/docs-panel-drag-drop.webm
new file mode 100644
index 0000000000..d6c3815151
Binary files /dev/null and b/docs/_static/docs-panel-drag-drop.webm differ
diff --git a/docs/_static/docs-sidebar-developer-panel.jpg b/docs/_static/docs-sidebar-developer-panel.jpg
new file mode 100644
index 0000000000..2459de8e9c
Binary files /dev/null and b/docs/_static/docs-sidebar-developer-panel.jpg differ
diff --git a/docs/_static/docs-sidebar-developer-panel.webp b/docs/_static/docs-sidebar-developer-panel.webp
new file mode 100644
index 0000000000..bea5dc95fe
Binary files /dev/null and b/docs/_static/docs-sidebar-developer-panel.webp differ
diff --git a/docs/_static/docs-variables-panel.jpg b/docs/_static/docs-variables-panel.jpg
deleted file mode 100644
index c752143867..0000000000
Binary files a/docs/_static/docs-variables-panel.jpg and /dev/null differ
diff --git a/docs/_static/docs-variables-panel.webp b/docs/_static/docs-variables-panel.webp
deleted file mode 100644
index 0b6ef273e9..0000000000
Binary files a/docs/_static/docs-variables-panel.webp and /dev/null differ
diff --git a/docs/guides/editor_features/dataflow.md b/docs/guides/editor_features/dataflow.md
index df762ebd88..86aa0cabd0 100644
--- a/docs/guides/editor_features/dataflow.md
+++ b/docs/guides/editor_features/dataflow.md
@@ -20,8 +20,8 @@ variables in your notebook into a single searchable list.
<div align="center">
<picture>
- <source srcset="/_static/docs-variables-panel.webp" type="image/webp">
- <img src="/_static/docs-variables-panel.jpg" alt="Variables panel showing variable relationships" style="max-width: 700px; width: 100%;" />
+ <source srcset="/_static/docs-dataflow-variables-explorer.webp" type="image/webp">
+ <img src="/_static/docs-dataflow-variables-explorer.jpg" alt="Variables explorer panel showing variable names, types, and relationships" style="max-width: 700px; width: 100%;" />
</picture>
</div>
@@ -29,36 +29,32 @@ To open the panel, click the **variables icon** in the **left sidebar panel**.
The variable explorer shows each variable's name, type, value, where it's
defined, and where it's used.
-## Dependency explorer
+## Dependencies panel
-The **dependency explorer panel** provides a _bird's-eye view_ of your
-notebook's dataflow, showing all cells as an interactive graph. It helps you
-understand high-level patterns, overall connectedness, and the broader
-structure of your notebook.
+The **Dependencies panel** consolidates dataflow visualization tools into a
+single location with two tabs: **Minimap** (default) and **Graph**.
+
+To open it, click the **Dependencies icon** in the sidebar, or use the hotkey
+`Cmd/Ctrl-Shift-I` to toggle the panel.
<div align="center">
<picture>
- <source srcset="/_static/docs-dependency-explorer.webp" type="image/webp">
- <img src="/_static/docs-dependency-explorer.jpg" alt="Dependency explorer showing a graph view of cell connections" style="max-width: 700px; width: 100%;" />
+ <source srcset="/_static/docs-dataflow-dependencies-panel.webp" type="image/webp">
+ <img src="/_static/docs-dataflow-dependencies-panel.jpg" alt="Dependencies panel showing minimap and graph tabs" style="max-width: 700px; width: 100%;" />
</picture>
</div>
-To open the dependency explorer, click the **graph icon** in the **left sidebar
-panel**. You can choose between vertical or horizontal layouts.
-
-## Minimap
+### Minimap
-The **minimap** provides a _focused slice_ of your notebook's dataflow, helping
-you understand the reactive context of a given cell and navigate related cells.
-You can toggle the minimap a _hotkey_ (`Cmd/Ctrl-Shift-i`), or select the **map
-icon** from the **footer toolbar**.
+The **Minimap** tab (shown by default) provides a _focused slice_ of your
+notebook's dataflow, helping you understand the reactive context of a given
+cell and navigate related cells.
Click a cell in the minimap to jump to it:
<div align="center">
<video autoplay muted loop playsinline style="max-width: 700px; width: 100%;">
- <source src="/_static/docs-minimap.webm" type="video/webm">
- <source src="/_static/docs-minimap.mp4" type="video/mp4">
+ <source src="/_static/docs-dataflow-minimap.webm" type="video/webm">
</video>
</div>
@@ -73,8 +69,8 @@ only through one or more intermediate cells
The minimap can take some getting used to, but it's an effective representation
for understanding how data flows around the current cell. It's meant to show
_just enough_ local context to help you debug, trace relationships, and
-navigate complex notebooks. For a high level overview, use the [dependency
-explorer](#dependency-explorer).
+navigate complex notebooks. For a high level overview, use the [Graph
+view](#graph-view).
### Cell symbols
@@ -270,6 +266,20 @@ depends on. When tracing downstream, all variables in a dependent cell are
considered affected. Our minimap also accounts for marimo's support for
multi-column layouts.
+### Graph view
+
+The **Graph** tab provides a _bird's-eye view_ of your notebook's dataflow,
+showing all cells as an interactive graph. It helps you understand high-level
+patterns, overall connectedness, and the broader structure of your notebook.
+
+<div align="center">
+<picture>
+ <source srcset="/_static/docs-dataflow-graph.webp" type="image/webp">
+ <img src="/_static/docs-dataflow-graph.jpg" alt="Graph view showing all cells as an interactive dataflow graph" style="max-width: 700px; width: 100%;" />
+</picture>
+</div>
+
+You can choose between vertical or horizontal layouts for the graph.
## Reactive reference highlighting
diff --git a/docs/guides/editor_features/index.md b/docs/guides/editor_features/index.md
index 4620927478..a7264f5f4b 100644
--- a/docs/guides/editor_features/index.md
+++ b/docs/guides/editor_features/index.md
@@ -8,6 +8,7 @@ with code and data.
| Guide | Description |
| ------------------------------------------- | ------------------------------------------------ |
| [Overview](overview.md) | An overview of editor features and configuration |
+| [Sidebar and Developer Panel](panels.md) | Customize your workspace with panels |
| [Understanding dataflow](dataflow.md) | Visualize and navigate cell dependencies |
| [Package Management](package_management.md) | Using package managers in marimo |
| [AI Completion](ai_completion.md) | Code with the help of a language model |
diff --git a/docs/guides/editor_features/overview.md b/docs/guides/editor_features/overview.md
index 8a5db9e304..c4a5b0686f 100644
--- a/docs/guides/editor_features/overview.md
+++ b/docs/guides/editor_features/overview.md
@@ -111,23 +111,13 @@ When vim keybindings are enabled, press `Ctrl+Esc` (or `Cmd+Esc` on macOS, `Shif
Press `i` or `Enter` to return to cell editing.
-## Overview panels
-
-marimo ships with the IDE panels that provide an overview of your notebook
-
-- **file explorer**: view the file tree, open other notebooks
-- **variables**: explore variable values, see where they are defined and used, with go-to-definition
-- **data explorer**: see dataframe and table schemas at a glance
-- **dataflow tools**: visualize and navigate notebook structure and cell dependencies (see [Understanding dataflow](dataflow.md))
-- **package manager**: add and remove packages, and view your current environment
-- **table of contents**: corresponding to your markdown
-- **documentation** - move your text cursor over a symbol to see its documentation
-- **logs**: a continuous stream of stdout and stderr
-- **scratchpad**: a scratchpad cell where you can execute throwaway code
-- **snippets** - searchable snippets to copy directly into your notebook
-- **feedback** - share feedback!
-
-These panels can be toggled via the buttons in the left of the editor.
+## Sidebar and Developer Panel
+
+marimo organizes editor tools into two areas: the **sidebar** on the left for everyday notebook tools (files, variables, packages, AI, documentation), and the **developer panel** at the bottom for debugging utilities (errors, logs, terminal, tracing).
+
+You can customize both areas by dragging panels to reorder them or move them between sections. Toggle the sidebar with `Cmd/Ctrl-Shift-S` and the developer panel with `Cmd/Ctrl-J`.
+
+See the [Sidebar and Developer Panel](panels.md) guide for a complete list of available panels and customization options.
## Cell actions
diff --git a/docs/guides/editor_features/panels.md b/docs/guides/editor_features/panels.md
new file mode 100644
index 0000000000..e65788be65
--- /dev/null
+++ b/docs/guides/editor_features/panels.md
@@ -0,0 +1,73 @@
+# Sidebar and Developer Panel
+
+marimo organizes editor tools into two main areas: the **sidebar** on the left and the **developer panel** at the bottom. This layout keeps everyday notebook tools easily accessible while providing a dedicated space for debugging and development utilities.
+
+<div align="center">
+<picture>
+ <source srcset="/_static/docs-sidebar-developer-panel.webp" type="image/webp">
+ <img src="/_static/docs-sidebar-developer-panel.jpg" alt="Editor showing sidebar on the left and developer panel at the bottom" style="max-width: 700px; width: 100%;" />
+</picture>
+</div>
+
+## Sidebar
+
+The sidebar provides quick access to panels you'll use frequently while working on notebooks. Click the icons on the left edge of the editor to open panels.
+
+**Default sidebar panels:**
+
+| Panel | Description |
+|-------|-------------|
+| **Files** | Browse and open files in your workspace |
+| **Variables** | Explore variables and data sources in your notebook |
+| **Packages** | View installed packages and manage dependencies |
+| **AI** | Chat with AI assistants and use agents |
+| **Outline** | Navigate your notebook via table of contents |
+| **Documentation** | View live documentation as you type |
+| **Dependencies** | Visualize cell relationships with the minimap and dependency graph |
+
+Toggle the sidebar with `Cmd/Ctrl-Shift-S`.
+
+## Developer Panel
+
+The developer panel houses tools for debugging, tracing execution, and other advanced functionality. It appears at the bottom of the editor, similar to the developer tools in VS Code or browser DevTools.
+
+**Default developer panel tabs:**
+
+| Panel | Description |
+|-------|-------------|
+| **Errors** | View all errors across your notebook |
+| **Scratchpad** | A scratch cell for quick experiments without affecting your notebook |
+| **Tracing** | Monitor cell execution and performance |
+| **Secrets** | Manage environment secrets |
+| **Logs** | View stdout and stderr output |
+| **Terminal** | Integrated terminal for shell commands |
+| **Snippets** | Browse and insert code snippets |
+
+Toggle the developer panel with `Cmd/Ctrl-J`.
+
+<!-- TODO: Add screenshot of developer panel expanded -->
+
+## Customizing your layout
+
+Both the sidebar and developer panel are fully customizable. You can:
+
+- **Reorder panels**: Drag panels to rearrange their order within a section
+- **Move panels between sections**: Drag a panel from the sidebar to the developer panel (or vice versa) to relocate it
+- **Hide panels**: Right-click a panel icon to access options for hiding or moving it
+
+Your layout preferences are saved and persist across sessions. Panels automatically adapt their appearance based on their location — showing a more compact vertical layout in the sidebar and a wider horizontal layout in the developer panel.
+
+<div align="center">
+<video autoplay muted loop playsinline style="max-width: 700px; width: 100%; border-radius: 8px;">
+ <source src="/_static/docs-panel-drag-drop.webm" type="video/webm">
+</video>
+</div>
+
+## Keyboard shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Cmd/Ctrl-J` | Toggle developer panel |
+| `Cmd/Ctrl-Shift-S` | Toggle sidebar |
+| `Cmd/Ctrl-Shift-I` | Open minimap (in Dependencies panel) |
+| `` Ctrl-` `` | Open terminal |
diff --git a/docs/guides/reactivity.md b/docs/guides/reactivity.md
index c6f7d7882f..b3f6adfc88 100644
--- a/docs/guides/reactivity.md
+++ b/docs/guides/reactivity.md
@@ -42,7 +42,7 @@ former. When a cell is run, its descendants are marked for execution.
!!! tip "Visualizing the DAG"
marimo provides several tools to help you visualize and navigate this dependency graph,
- including a [dependency explorer](editor_features/dataflow.md#dependency-explorer),
+ including a [dependency graph](editor_features/dataflow.md#graph-view),
[minimap](editor_features/dataflow.md#minimap),
and [reactive reference highlighting](editor_features/dataflow.md#reactive-reference-highlighting).
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index 085097b3d0..be6aac190e 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -42,8 +42,8 @@ defining `f` depends on the two cells above and connects to the one below with
Alternatively, you can open the [dependency
-explorer](editor_features/dataflow.md#dependency-explorer) or [variables
-explorer](editor_features/dataflow.md#variables-explorer) in the left sidebar.
+graph](editor_features/dataflow.md#graph-view) or [variables
+panel](editor_features/dataflow.md#variables-panel) in the sidebar.
<div align="center">
<figure>
diff --git a/frontend/src/components/editor/chrome/types.ts b/frontend/src/components/editor/chrome/types.ts
index 7c127f3a71..678cc0d7da 100644
--- a/frontend/src/components/editor/chrome/types.ts
+++ b/frontend/src/components/editor/chrome/types.ts
@@ -95,13 +95,6 @@ export const PANELS: PanelDescriptor[] = [
tooltip: "Chat & Agents",
defaultSection: "sidebar",
},
- {
- type: "snippets",
- Icon: SquareDashedBottomCodeIcon,
- label: "Snippets",
- tooltip: "Snippets",
- defaultSection: "developer-panel",
- },
{
type: "outline",
Icon: ScrollTextIcon,
@@ -169,6 +162,13 @@ export const PANELS: PanelDescriptor[] = [
defaultSection: "developer-panel",
requiredCapability: "terminal",
},
+ {
+ type: "snippets",
+ Icon: SquareDashedBottomCodeIcon,
+ label: "Snippets",
+ tooltip: "Snippets",
+ defaultSection: "developer-panel",
+ },
{
type: "cache",
Icon: DatabaseZapIcon,
diff --git a/mkdocs.yml b/mkdocs.yml
index 7b3081f024..783aed547f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -115,6 +115,7 @@ nav:
- Editor features: guides/editor_features/index.md
- Editor overview: guides/editor_features/overview.md
- Home page: guides/editor_features/home.md
+ - Sidebar and Developer Panel: guides/editor_features/panels.md
- Understanding dataflow: guides/editor_features/dataflow.md
- Module autoreloading: guides/editor_features/module_autoreloading.md
- Hotkeys: guides/editor_features/hotkeys.md