From 354a102a184b3be865ea081cdc2e23662fae4657 Mon Sep 17 00:00:00 2001
From: Akshay Agrawal <akshay@marimo.io>
Date: Fri, 30 Aug 2024 11:57:17 -0700
Subject: [PATCH] improve md format tutorial

---
 marimo/_tutorials/markdown_format.md | 104 +++++++++++++--------------
 1 file changed, 48 insertions(+), 56 deletions(-)

diff --git a/marimo/_tutorials/markdown_format.md b/marimo/_tutorials/markdown_format.md
index bd44ead630b..2eb42f0196e 100644
--- a/marimo/_tutorials/markdown_format.md
+++ b/marimo/_tutorials/markdown_format.md
@@ -3,39 +3,52 @@ title: Markdown
 marimo-version: 0.4.11
 ---
 
-# marimo in Markdown!
+# Markdown file format
 
-Everything in marimo is pure Python, but sometimes, annotating your notebook
-in markdown can be a little cumbersome.
+By default, marimo notebooks are stored as pure Python files. However,
+you can also store and edit marimo notebooks as `.md` files, letting you
+work on prose-heavy marimo notebooks in your editor of choice.
+
+_Make sure to look at the markdown
+[source code](https://github.com/marimo-team/marimo/blob/main/marimo/_tutorials/markdown_format.md)
+of this tutorial!_
+<!---->
+When using the markdown file format, you can write and save markdown directly,
+and marimo will execute the necessary Python code for you behind the scenes.
+This allows you to focus on prose, and not formatting your text in a block
+string.
 <!---->
-For example, here's the code that rendered the above title and
-paragraph:
+## Running markdown notebooks
 
-````md
-```{python}
-mo.md(
-    '''
-    # marimo in Markdown!
+To edit a markdown notebook, use
 
-    Everything in marimo is pure Python, but sometimes, annotating your notebook
-    in markdown can be a little cumbersome.
-    '''
-)
+```bash
+$ marimo edit notebook.md
 ```
-````
 
-with markdown notebook support for marimo, you can write and save markdown
-directly, and marimo will execute the necessary Python code for you behind the
-scenes. This allows you to focus on prose, and not formatting your text in a block
-string.
+To run it as an app, use
+
+```bash
+$ marimo run notebook.md
+```
 <!---->
-## Python cells in markdown
+## Exporting from Python
+
+You can export marimo notebooks that are stored as Python to the markdown format
+by running the following command:
+
+```bash
+$ marimo export md notebook.py > notebook.md
+```
+<!---->
+
+## Creating Python cells
 
 When you do need to create a Python cell in the markdown format, you can use a
 special code block:
 
 ````md
-```{python}
+```{.python.marimo}
 import matplotlib.pyplot as plt
 plt.plot([1, 2, 3, 4])
 ```
@@ -52,21 +65,6 @@ plt.gca()
 As long as your code block contains the word `python` in a brace, like
 `{python}`, or `{.python note="Whatever you want"}`, marimo will treat it as a
 Python cell.
-<!---->
-## Exporting from Python
-
-Do you have a notebook that you think might better be suited for a markdown notebook?
-You can export your notebook to markdown by running the following code:
-
-```bash
-$ marimo export md my_marimo.py > my_marimo.md
-```
-
-by default, marimo will extract your markdown cells, and wrap your Python cells
-in `{.python.marimo}` code blocks. Although `{python}` might be more concise,
-this format is chosen such that code highlighting will work in your favourite
-IDE.
-<!---->
 ## `mo` tricks and tips
 
 You can break up markdown into multiple cells by using an empty html tag `<!---->`:
@@ -121,10 +119,9 @@ print("This code cell has a syntax error"
 
 marimo's markdown support treats markdown as just plain old markdown. This
 means that trying to use string interpolation (like this `f"{'🍃' * 7}"`) will
-just give you the raw string. This is a benefit, as you can clearly delineate
-what values are supposed to be computed, and what values are static;
-
-and there's nothing stopping you from executing python to achieve the same effect,
+just give you the raw string. This lets you clearly delineate what values are
+supposed to be computed, and what values are static. To interpolate Python
+values, just use a Python cell:
 
 ```{.python.marimo}
 '🍃' * 7
@@ -147,7 +144,7 @@ some ambiguous cases can't be converted to markdown like this:
 mo.md("""
   This is a markdown cell with an execution block in it
   ```{python}
-  # To ambiguous to convert
+  # Too ambiguous to convert
   ```
   """)
 ````
@@ -156,14 +153,14 @@ It's not likely that you'll run into this issue, but rest assured that marimo
 is working behind the scenes to keep your notebooks unambiguous and clean as
 possible.
 <!---->
-### More limitations
+### Naming cells
 
 Since the markdown notebook really is just markdown, you can't import from a
 markdown notebook cells like you can in a python notebook; but you can still
 give your cells a name:
 
 ````md
-```{python name="maybe"}
+```{.python.marimo name="maybe"}
 # 🎵 Hey, I just met you, and this is crazy
 ```
 ````
@@ -172,24 +169,19 @@ give your cells a name:
 # But here's my `cell_id`, so call me, `maybe` 🎶
 ```
 
-you can even run a notebook:
-
-```bash
-$ marimo run my_marimo.md
-```
-
-the markdown format is supposed to lower the barrier for writing text heavy
-documents, it's not meant to be a full replacement for the python notebook
-format. You can always convert back to a python notebook if you need to:
+## Converting back to the Python file format
+The markdown format is supposed to lower the barrier for writing text heavy
+documents, it's not meant to be a full replacement for the Python notebook
+format. You can always convert back to a Python notebook if you need to:
 
 ```bash
 $ marimo convert my_marimo.md > my_marimo.py
 ```
-<!---->
-## More?!
 
-Be sure to checkout the markdown.py tutorial for more information on to type-set
-and render markdown in marimo.
+## More on markdown
+
+Be sure to checkout the markdown.py tutorial (`marimo tutorial markdown`) for
+more information on to type-set and render markdown in marimo.
 
 ```{.python.marimo hide_code="true"}
 import marimo as mo