Create example & update docs for multi-page navigation

docs/guides/pages.md

@@ -4,7 +4,7 @@ You can define multi-page Mesop applications by using the page feature you learn
 
 ## Simple, 1-page setup
 
-If you want to create a simple Mesop app, you can do the following:
+To create a simple Mesop app, you can use `me.page()` like this:
 
 ```python
 import mesop as me
@@ -14,10 +14,12 @@ def foo():
     me.text("bar")
 ```
 
-This is the same as the following example which more explicitly sets the route to `"/"`.
+> NOTE: If you do not provide a `path` argument, then it defaults to the root path `"/"`.
 
 ## Explicit 1-page setup
 
+This is the same as the above example which explicitly sets the route to `"/"`.
+
 ```python
 import mesop as me
 
@@ -39,3 +41,15 @@ def page1():
 def page2():
     me.text("page 2")
 ```
+
+## Navigation
+
+If you have multiple pages, you will typically want to navigate from one page to another when the user clicks a button. You can use `me.navigate("/to/path")` to navigate to another page.
+
+**Example:**
+
+```python
+--8<-- "mesop/examples/docs/multi_page_nav.py"
+```
+
+> Note: you can re-use state across pages. See how the above example uses the `State#count` value across pages.

mesop/examples/docs/__init__.py

@@ -1,4 +1,5 @@
 from mesop.examples.docs import counter as counter
 from mesop.examples.docs import hello_world as hello_world
 from mesop.examples.docs import loading as loading
+from mesop.examples.docs import multi_page_nav as multi_page_nav
 from mesop.examples.docs import streaming as streaming

mesop/examples/docs/multi_page_nav.py

@@ -0,0 +1,23 @@
+import mesop as me
+
+
+def on_click(e: me.ClickEvent):
+  state = me.state(State)
+  state.count += 1
+  me.navigate("/multi_page_nav/page_2")
+
+
+@me.page(path="/multi_page_nav")
+def main_page():
+  me.button("Navigate to Page 2", on_click=on_click)
+
+
+@me.page(path="/multi_page_nav/page_2")
+def page_2():
+  state = me.state(State)
+  me.text(f"Page 2 - count: {state.count}")
+
+
+@me.stateclass
+class State:
+  count: int