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.

docs: clean up organization (#7464)

Akshay Agrawalf3382e3802d3
diff --git a/docs/guides/debugging.md b/docs/guides/debugging.md
index 810a9e938d..7baed9a37d 100644
--- a/docs/guides/debugging.md
+++ b/docs/guides/debugging.md
@@ -1,39 +1,16 @@
-# Debugging marimo notebooks
+# Debugging
-## Debugging in marimo
+## In the marimo editor
-### Using pdb in marimo notebooks
+### Setting breakpoints with pdb
-marimo has direct support for pdb, the Python debugger. You can set breakpoints
-in your code using the built-in `breakpoint()` function. When the code
-execution reaches a breakpoint, it will pause, and you can inspect variables,
-step through the code, and evaluate expressions.
+marimo supports pdb, the Python debugger. Set breakpoints in your code using
+the built-in `breakpoint()` function. When the code execution reaches a
+breakpoint, it will pause, and you can inspect variables, step through the
+code, and evaluate expressions.
-Here's an example of how to use `breakpoint()` in a marimo notebook cell.
-
-![PDB in marimo](../_static/docs-pdb-demo.png)
-
-Type `help` in the debugger for a list of commands:
-
-```txt
-Documented commands (type help <topic>):
-========================================
-EOF cl disable ignore n return u where
-a clear display interact next retval unalias
-alias commands down j p run undisplay
-args condition enable jump pp rv unt
-b cont exceptions l q s until
-break continue exit list quit source up
-bt d h ll r step w
-c debug help longlist restart tbreak whatis
-
-Miscellaneous help topics:
-==========================
-exec pdb
-```
-
-!!! note
- Since this block is runnable, you can test the debugger directly
+Here's a live example of how to use `breakpoint()` in a marimo notebook cell. Type
+`help` in the debugger for a list of commands.
/// marimo-embed
@@ -52,11 +29,18 @@ def _():
return
```
+
///
-!!! tip
+!!! warning "The debugger blocks execution"
+
+ When the debugger is active, you cannot execute cells. Remember to continue
+ or quit the debugger to avoid hanging the notebook!
+
+??? note "Adding breakpoints in the stack trace"
Click the little bug icon in the stack trace to add breakpoints.
- <video autoplay muted loop playsinline width="100%" align="center" src="/_static/docs-pdb-breakpoint.webm" alt="Animation showing how to click the bug icon to add PDB breakpoints">
+
+ <video muted controls playsinline width="100%" align="center" src="/_static/docs-pdb-breakpoint.webm" alt="Animation showing how to click the bug icon to add PDB breakpoints">
</video>
Clicking on the cell link will also take you to the cell where the error occurred.
@@ -66,25 +50,24 @@ If your code raises an exception, you can use postmortem debugging to inspect
the state of the program at the point where the exception occurred. Click on
the "Launch debugger" button as shown below:
-<video autoplay muted loop playsinline width="100%" align="center" src="/_static/docs-postmortem-debugging.webm" alt="Video demonstrating postmortem debugging with the Launch debugger button">
+<video muted controls playsinline width="100%" align="center" src="/_static/docs-postmortem-debugging.webm" alt="Video demonstrating postmortem debugging with the Launch debugger button">
</video>
+## Debugging notebooks as scripts
-!!! note
- Other tools like the following will also work in marimo notebooks:
-
- ```python
- import code
- code.interact()
- return
- ```
+Since marimo notebooks are standard Python files, you can run them as scripts
+from the command line. The following command will run your marimo notebook and
+drop you into the pdb debugger if an exception occurs, or if you hit a
+breakpoint.
-!!! danger
- Remember to continue or quit the debugger to avoid hanging the notebook!
+```bash
+python -m pdb your_script.py
+```
-## Tips for debugging marimo notebooks with AI
+## Debugging with AI
-marimo provides built-in integration with AI assistants to help debug your notebooks more effectively.
+marimo provides built-in integration with AI assistants to help you debug your
+notebooks.
### Ask about notebook errors
@@ -117,26 +100,17 @@ advice.
concepts like reactive execution, cell dependencies, and the differences
between marimo notebooks and traditional Jupyter notebooks.
-## Debugging notebooks as a script
-Since marimo notebooks are standard Python files, you can run them as scripts
-from the command line. The following command will run your marimo notebook and
-drop you into the pdb debugger if an exception occurs, or if you hit a
-breakpoint.
-
-```bash
-python -m pdb your_script.py
-```
-
-## External IDE debugging with `debugpy`
+## Integrating with external IDEs
-marimo supports debugging with IDEs, like VSCode, which natively support the
+marimo supports debugging with IDEs, like VS Code, which natively support the
`debugpy` library. This allows you to set breakpoints, step through code, and
inspect variables directly from your IDE.
-### Script mode
-You can debug marimo notebooks in VSCode using the following `launch.json`.
-This launch configuration will debug a marimo notebook in [script
-mode](./scripts.md).
+### Running as scripts
+
+You can debug marimo notebooks in VS Code using the following `launch.json`.
+This launch configuration will debug a marimo notebook executing it as a
+[script](./scripts.md).
```json
{
@@ -155,9 +129,10 @@ mode](./scripts.md).
}
```
-### Edit mode
+### Interactive development
+
Edit mode debugging allows the marimo editor to trigger breakpoints set in an
-IDE like VSCode. Running in this mode will automatically start your notebook in
+IDE like VS Code. Running in this mode will automatically start your notebook in
[watch mode](./editor_features/watching.md). Note that the file state and
editor must be consistent for break points to correctly work. If debugging is
not acting as expected, force a notebook save and toggle the relevant
@@ -185,18 +160,12 @@ Use the following `launch.json` configuration to enable edit mode debugging:
}
```
-<video autoplay muted loop playsinline width="100%" align="center" src="/_static/docs-debugpy-edit-mode.webm" alt="Video showing debugpy edit mode debugging with VSCode hitting marimo breakpoints">
+<video muted controls loop playsinline width="100%" align="center" src="/_static/docs-debugpy-edit-mode.webm" alt="Video showing debugpy edit mode debugging with VS Code hitting marimo breakpoints">
</video>
!!! note
This will disable marimo's internal debugging features.
!!! danger
- This mode is blocking in VSCode, so you will need to interact with the
+ This mode is blocking in VS Code, so you will need to interact with the
debugger in your editor to regain control of the marimo notebook.
-
-
-## Debug directly in VSCode
-
-!!! note
- LSP support for marimo notebooks is coming soon, along with native debug server integration.
diff --git a/docs/guides/editor_features/watching.md b/docs/guides/editor_features/watching.md
index 6c49af7f71..cf320c483f 100644
--- a/docs/guides/editor_features/watching.md
+++ b/docs/guides/editor_features/watching.md
@@ -7,7 +7,7 @@ the marimo editor or running application. This lets you edit your notebook
using an editor of your choice, like neovim, VSCode, Cursor, or PyCharm, and
have the changes automatically reflected in your browser.
-/// admonition | Prefer VS Code/Cursor?
+/// admonition | Prefer VS Code/Cursor? Try our extension!
type: tip
This guide teaches you how to use marimo with arbitrary text editors.
diff --git a/docs/guides/lint_rules/index.md b/docs/guides/lint_rules/index.md
index 1cfa916e88..8b7febcde3 100644
--- a/docs/guides/lint_rules/index.md
+++ b/docs/guides/lint_rules/index.md
@@ -1,10 +1,12 @@
# Lint Rules
-marimo includes a comprehensive linting system that helps you write better, more reliable notebooks. The linter checks for various issues that could prevent your notebook from running correctly or cause confusion.
+marimo includes a linter that helps you write better notebooks. The linter
+checks for various issues that could prevent your notebook from running
+correctly or cause confusion.
-## How to Use
+## Usage
-You can run the linter using the CLI:
+Run the linter using the CLI:
```bash
# Check all notebooks in current directory
diff --git a/docs/guides/publishing/embedding.md b/docs/guides/publishing/embedding.md
index 50888b09e2..a15e91f175 100644
--- a/docs/guides/publishing/embedding.md
+++ b/docs/guides/publishing/embedding.md
@@ -7,12 +7,9 @@ are the main approaches:
* Host on [GitHub Pages](github_pages.md) or [self-host WASM HTML](self_host_wasm.md),
and `<iframe>` the published notebook.
* `<iframe>` a [playground](playground.md) notebook, and [customize the embedding](playground.md#embedding-in-other-web-pages) with query params.
- (This is what we do throughout docs.marimo.io.)
+ (This is what we do throughout https://docs.marimo.io.)
* Use the [marimo snippets](from_code_snippets.md) plugin to replace code snippets in HTML or markdown with interactive notebooks.
-We plan to provide more turn-key solutions for static site generation with
-marimo notebooks in the future.
-
## Iframe Sandbox Configuration
When embedding marimo notebooks in sandboxed iframes, proper configuration is essential for full functionality. marimo is designed to gracefully degrade when certain features are restricted, but understanding these requirements will help you provide the best experience.
diff --git a/docs/guides/publishing/from_github.md b/docs/guides/publishing/from_github.md
index 0728f63c39..7fa0820726 100644
--- a/docs/guides/publishing/from_github.md
+++ b/docs/guides/publishing/from_github.md
@@ -6,7 +6,7 @@ data stored in your GitHub repo to the notebook's filesystem, making it
easy to bundle data with your notebooks.
+- [Share molab links](https://molab.marimo.io/github) to notebooks hosted on GitHub
- Publish notebooks to [GitHub Pages](github_pages.md)
- Edit notebooks on the [marimo playground](playground.md), with public link-based sharing
(no login required!)
-- Synchronize to our [Community Cloud](community_cloud/index.md) for email-based sharing
diff --git a/docs/guides/publishing/index.md b/docs/guides/publishing/index.md
index 70e6bcfeef..d82936cc97 100644
--- a/docs/guides/publishing/index.md
+++ b/docs/guides/publishing/index.md
@@ -1,15 +1,20 @@
# Publishing notebooks to the web
You can publish marimo notebooks to the web as interactive editable notebooks,
-readonly web apps, or [static documents](../exporting.md).
-
-Thanks to [WebAssembly](../wasm.md), you can even share executable
-notebooks on GitHub Pages or other static sites without paying for backend
-infrastrcture. This makes it easy to share your work with colleagues, embed
-executable notebooks in web documentation or educational websites, and more.
+readonly web apps, or [static documents](../exporting.md). Thanks to
+[WebAssembly](../wasm.md), you can even share executable notebooks on GitHub
+Pages or other static sites without paying for backend infrastrcture. This
+makes it easy to share your work with colleagues, embed executable notebooks in
+web documentation or educational websites, and more.
This guide provides an overview of the various ways to publish marimo notebooks.
+!!! tip "Share cloud-hosted notebooks with molab"
+
+ For a turn-key sharing experience, use [molab](https://molab.marimo.io/notebooks),
+ our free cloud-hosted marimo notebook
+
+
| Guide | Description |
| ----------------------------------------------------- | ------------------------------------------------------------ |
| [Embedding](embedding.md) | An overview of embedding notebooks in other sites |
@@ -17,10 +22,8 @@ This guide provides an overview of the various ways to publish marimo notebooks.
| [From code snippets](from_code_snippets.md) | Convert code snippets in Markdown or HTML to interactive notebooks |
| [GitHub Pages](github_pages.md) | Publish interactive notebooks on GitHub Pages |
| [Cloudflare](cloudflare.md) | Publish interactive notebooks on Cloudflare |
-| [Online playground](playground.md) | Share links to notebooks using our online playground |
-| [Community Cloud](community_cloud/index.md) | Save notebooks to our free Community Cloud |
| [Self-host WebAssembly notebooks](self_host_wasm.md) | Self-hosting interactive WebAssembly (HTML export) notebooks |
+| [Online playground](playground.md) | Share links to notebooks using our online playground |
| [View notebooks on GitHub](view_outputs_on_github.md) | Viewing notebook outputs on GitHub |
| [Deploy on a backend](deploy.md) | Deploying notebooks on backends |
-| [With MkDocs](mkdocs.md) | Publish reactive websites with MkDocs from markdown |
| [With Quarto](quarto.md) | Publish reactive websites with Quarto from markdown |
diff --git a/mkdocs.yml b/mkdocs.yml
index 009cc394f8..0dc49a284b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -85,6 +85,11 @@ nav:
- Running cells: guides/reactivity.md
- Interactive elements: guides/interactivity.md
- Visualize outputs: guides/outputs.md
+ - SQL, dataframes, and plots:
+ - SQL, dataframes, and plots: guides/working_with_data/index.md
+ - DataFrames: guides/working_with_data/dataframes.md
+ - SQL: guides/working_with_data/sql.md
+ - Plotting: guides/working_with_data/plotting.md
- Migrate from Jupyter: guides/coming_from/jupyter.md
- Expensive notebooks: guides/expensive_notebooks.md
- Understanding errors:
@@ -93,29 +98,6 @@ nav:
- Import star: guides/understanding_errors/import_star.md
- Cycles: guides/understanding_errors/cycles.md
- Setup References: guides/understanding_errors/setup.md
- - Debugging notebooks: guides/debugging.md
- - Lint Rules:
- - Lint Rules: guides/lint_rules/index.md
- - Rules:
- - Unparsable cells: guides/lint_rules/rules/unparsable_cells.md
- - Multiple definitions: guides/lint_rules/rules/multiple_definitions.md
- - Cycle dependencies: guides/lint_rules/rules/cycle_dependencies.md
- - Setup cell dependencies: guides/lint_rules/rules/setup_cell_dependencies.md
- - Syntax error: guides/lint_rules/rules/invalid_syntax.md
- - Self Import: guides/lint_rules/rules/self_import.md
- - Branch expression: guides/lint_rules/rules/branch_expression.md
- - General formatting: guides/lint_rules/rules/general_formatting.md
- - Parse stdout: guides/lint_rules/rules/parse_stdout.md
- - Parse stderr: guides/lint_rules/rules/parse_stderr.md
- - Empty cells: guides/lint_rules/rules/empty_cells.md
- - Markdown Indentation: guides/lint_rules/rules/markdown_indentation.md
- - SQL parse error: guides/lint_rules/rules/sql_parse_error.md
- - Misc parse log: guides/lint_rules/rules/misc_log_capture.md
- - SQL, dataframes, and plots:
- - SQL, dataframes, and plots: guides/working_with_data/index.md
- - DataFrames: guides/working_with_data/dataframes.md
- - SQL: guides/working_with_data/sql.md
- - Plotting: guides/working_with_data/plotting.md
- Package management:
- Package management: guides/package_management/index.md
- Importing packages: guides/package_management/importing_packages.md
@@ -127,39 +109,37 @@ nav:
- Generate with AI: guides/generate_with_ai/index.md
- Generate entire notebooks: guides/generate_with_ai/text_to_notebook.md
- AI-assisted coding: guides/editor_features/ai_completion.md
- - Prompts for the marimo editor: guides/generate_with_ai/prompts.md
+ - Prompts: guides/generate_with_ai/prompts.md
- Editor features:
- Editor features: guides/editor_features/index.md
- Editor overview: guides/editor_features/overview.md
- Understanding dataflow: guides/editor_features/dataflow.md
+ - Module autoreloading: guides/editor_features/module_autoreloading.md
+ - Hotkeys: guides/editor_features/hotkeys.md
- AI completion: guides/editor_features/ai_completion.md
- Model Context Protocol: guides/editor_features/mcp.md
- AI tools: guides/editor_features/tools.md
- Agents: guides/editor_features/agents.md
- Language Server: guides/editor_features/language_server.md
- Package management: guides/editor_features/package_management.md
- - Module autoreloading: guides/editor_features/module_autoreloading.md
- - Hotkeys: guides/editor_features/hotkeys.md
- Using your own editor: guides/editor_features/watching.md
- Run notebooks as apps: guides/apps.md
- Run notebooks as scripts: guides/scripts.md
- Reuse functions and classes: guides/reusing_functions.md
- - Test notebooks:
- - Testing notebooks: guides/testing/index.md
- - pytest: guides/testing/pytest.md
- - doctest: guides/testing/doctest.md
- Export to other formats: guides/exporting.md
- - Share cloud notebooks with molab: guides/molab.md
+ - Cloud notebooks with molab: guides/molab.md
- Publish to the web:
- Publish to the web: guides/publishing/index.md
- - Embedding: guides/publishing/embedding.md
- - From code snippets: guides/publishing/from_code_snippets.md
+ - Embedding:
+ - Embedding: guides/publishing/embedding.md
+ - From code snippets: guides/publishing/from_code_snippets.md
- From GitHub: guides/publishing/from_github.md
- - GitHub Pages: guides/publishing/github_pages.md
- - Cloudflare: guides/publishing/cloudflare.md
- - Online playground: guides/publishing/playground.md
- - Community Cloud: guides/publishing/community_cloud/index.md
- - Self-host WASM: guides/publishing/self_host_wasm.md
+ - Static sites:
+ - GitHub Pages: guides/publishing/github_pages.md
+ - Cloudflare: guides/publishing/cloudflare.md
+ - Quarto: guides/publishing/quarto.md
+ - Self-host WebAssembly notebooks: guides/publishing/self_host_wasm.md
+ - Share playground notebooks: guides/publishing/playground.md
- View outputs on GitHub: guides/publishing/view_outputs_on_github.md
- Deploy a backend: guides/publishing/deploy.md
- Deployment:
@@ -167,7 +147,6 @@ nav:
- Authentication: guides/deploying/authentication.md
- Docker: guides/deploying/deploying_docker.md
- HuggingFace: guides/deploying/deploying_hugging_face.md
- - Ploomber: guides/deploying/deploying_ploomber.md
- Public gallery: guides/deploying/deploying_public_gallery.md
- Railway: guides/deploying/deploying_railway.md
- nginx: guides/deploying/deploying_nginx.md
@@ -183,16 +162,38 @@ nav:
- Theming: guides/configuration/theming.md
- Snippets: guides/configuration/snippets.md
- i18n: guides/configuration/internationalization.md
+ - Extending marimo:
+ - Extending marimo: guides/integrating_with_marimo/index.md
+ - Custom UI plugins: guides/integrating_with_marimo/custom_ui_plugins.md
+ - Displaying objects: guides/integrating_with_marimo/displaying_objects.md
- Coming from other tools:
- Coming from other tools: guides/coming_from/index.md
- Jupytext: guides/coming_from/jupytext.md
- Papermill: guides/coming_from/papermill.md
- Streamlit: guides/coming_from/streamlit.md
- - Extending marimo:
- - Extending marimo: guides/integrating_with_marimo/index.md
- - Custom UI plugins: guides/integrating_with_marimo/custom_ui_plugins.md
- - Displaying objects: guides/integrating_with_marimo/displaying_objects.md
- Best practices: guides/best_practices.md
+ - Debugging: guides/debugging.md
+ - Linting:
+ - Lint Rules: guides/lint_rules/index.md
+ - Rules:
+ - Unparsable cells: guides/lint_rules/rules/unparsable_cells.md
+ - Multiple definitions: guides/lint_rules/rules/multiple_definitions.md
+ - Cycle dependencies: guides/lint_rules/rules/cycle_dependencies.md
+ - Setup cell dependencies: guides/lint_rules/rules/setup_cell_dependencies.md
+ - Syntax error: guides/lint_rules/rules/invalid_syntax.md
+ - Self Import: guides/lint_rules/rules/self_import.md
+ - Branch expression: guides/lint_rules/rules/branch_expression.md
+ - General formatting: guides/lint_rules/rules/general_formatting.md
+ - Parse stdout: guides/lint_rules/rules/parse_stdout.md
+ - Parse stderr: guides/lint_rules/rules/parse_stderr.md
+ - Empty cells: guides/lint_rules/rules/empty_cells.md
+ - Markdown Indentation: guides/lint_rules/rules/markdown_indentation.md
+ - SQL parse error: guides/lint_rules/rules/sql_parse_error.md
+ - Misc parse log: guides/lint_rules/rules/misc_log_capture.md
+ - Testing:
+ - Testing notebooks: guides/testing/index.md
+ - pytest: guides/testing/pytest.md
+ - doctest: guides/testing/doctest.md
- Troubleshooting: guides/troubleshooting.md
- Dangerously set state: guides/state.md
- Examples:
diff --git a/pyproject.toml b/pyproject.toml
index fe614d33a8..5c49205f3c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -294,7 +294,8 @@ dependencies = [
"marimo_docs @ file://docs",
"ruff>=0.13.2",
"mkdocs>=1.6.1",
- "mkdocs-material>=9.5.49",
+ # Live reloading broken in >= 9.6.21: https://github.com/squidfunk/mkdocs-material/issues/8478
+ "mkdocs-material==9.6.20",
"mkdocstrings[python]>=0.27.0",
"mkdocs-material-extensions>=1.3.1",
"mkdocs-autorefs>=1.2.0",