docs: more styling and admonitions (#3227)

marimo-team · Dec 19, 2024 · fef7cc6 · fef7cc6
1 parent a77fe03
commit fef7cc6
Show file tree

Hide file tree

Showing 12 changed files with 52 additions and 46 deletions.
diff --git a/docs/faq.md b/docs/faq.md
@@ -281,7 +281,7 @@ other outputs. If you're using matplotlib, you can display the `Figure` object
 marimo tutorial plots
 ```
 
-Also see the <a href="/api/plotting.html">plotting API reference</a>.
+Also see the [plotting API reference](api/plotting.md).
 
 <a name="faq-mpl-cutoff"></a>
 

diff --git a/docs/guides/configuration/runtime_configuration.md b/docs/guides/configuration/runtime_configuration.md
@@ -45,12 +45,12 @@ when working on notebooks with expensive cells.
 
 !!! tip "Tip: speed up expensive notebooks with marimo's smart caching"
 
-In addition to runtime configuration, marimo also provides [opt-in caching](../../api/caching.md)
-to help you work with expensive or side-effectful notebooks. marimo's
-can cache expensive functions in memory and expensive blocks of code to disk,
-letting you skip entire sections of your code and automatically loading
-variables in memory on notebook startup. Read our [caching
-guide](../../api/caching.md) to learn more.
+    In addition to runtime configuration, marimo also provides [opt-in caching](../../api/caching.md)
+    to help you work with expensive or side-effectful notebooks. marimo's
+    can cache expensive functions in memory and expensive blocks of code to disk,
+    letting you skip entire sections of your code and automatically loading
+    variables in memory on notebook startup. Read our [caching
+    guide](../../api/caching.md) to learn more.
 
 _When sharing a notebook as an app with `marimo run`, this setting has
 no effect._
@@ -64,9 +64,9 @@ modifications for modules imported by your notebook's imported modules too.
 
 !!! tip "Why autoreload?"
 
-Autoreloading enables a workflow that many developers find
-productive: develop complex logic in Python modules, and use the marimo
-notebook as a DAG or main script that orchestrates your logic.
+    Autoreloading enables a workflow that many developers find
+    productive: develop complex logic in Python modules, and use the marimo
+    notebook as a DAG or main script that orchestrates your logic.
 
 Autoreloading comes in two types:
 

diff --git a/docs/guides/configuration/theming.md b/docs/guides/configuration/theming.md
@@ -20,7 +20,7 @@ We support only a few CSS variables as part of the "public API" for theming. The
 
 !!! warning "Other CSS Variables"
 
-We cannot guarantee that other CSS variables or classnames will be stable across versions.
+    We cannot guarantee that other CSS variables or classnames will be stable across versions.
 
 ## Example
 

diff --git a/docs/guides/exporting.md b/docs/guides/exporting.md
@@ -43,8 +43,8 @@ its visual outputs before saving as HTML.
 
 !!! note "Note"
 
-If any cells error during the export process, the status code will be non-zero. However, the export result may still be generated, with the error included in the output.
-Errors can be ignored by appending `|| true` to the command, e.g. `marimo export html notebook.py || true`.
+    If any cells error during the export process, the status code will be non-zero. However, the export result may still be generated, with the error included in the output.
+    Errors can be ignored by appending `|| true` to the command, e.g. `marimo export html notebook.py || true`.
 
 ## Export to a Python script
 
@@ -57,9 +57,9 @@ marimo export script notebook.py -o notebook.script.py
 
 !!! warning "Top-level await not supported"
 
-Exporting to a flat Python script does not support top-level await. If you have
-top-level await in your notebook, you can still execute the notebook as a
-script with `python notebook.py`.
+    Exporting to a flat Python script does not support top-level await. If you have
+    top-level await in your notebook, you can still execute the notebook as a
+    script with `python notebook.py`.
 
 ## Export to markdown
 
@@ -149,8 +149,8 @@ Options:
 
 !!! note "Note"
 
-The exported file must be served over HTTP to function correctly - it cannot be opened directly from the filesystem (file://).
-Your server must also serve the assets in the `assets` directory, next to the HTML file. For this reason, we recommend using the online playground if possible: <https://marimo.app>.
+  The exported file must be served over HTTP to function correctly - it cannot be opened directly from the filesystem (file://).
+  Your server must also serve the assets in the `assets` directory, next to the HTML file. For this reason, we recommend using the online playground if possible: <https://marimo.app>.
 
 ### Testing the export
 
@@ -205,8 +205,8 @@ jobs:
 
 !!! note "Preview"
 
-Islands are an early feature. While the API likely won't change, there are some improvements we'd like to make before we consider them stable.
-Please let us know on [GitHub](https://github.com/marimo-team/marimo/issues) if you run into any issues or have any feedback!
+    Islands are an early feature. While the API likely won't change, there are some improvements we'd like to make before we consider them stable.
+    Please let us know on [GitHub](https://github.com/marimo-team/marimo/issues) if you run into any issues or have any feedback!
 
 marimo islands are a way to embed marimo outputs and/or python code in your HTML that will become interactive when the page is loaded. This is useful for creating interactive blog posts, tutorials, and educational materials, all powered by marimo's reactive runtime.
 
@@ -216,7 +216,7 @@ Check out an [example island-powered document](./island_example.md).
 
 !!! warning "Advanced topic!"
 
-Islands are an advanced concept that is meant to be a building block for creating integrations with existing tools such as static site generators or documentation tools.
+    Islands are an advanced concept that is meant to be a building block for creating integrations with existing tools such as static site generators or documentation tools.
 
 In order to use marimo islands, you need to import the necessary JS/CSS headers in your HTML file, and use our custom HTML tags to define the islands.
 

diff --git a/docs/guides/island_example.md b/docs/guides/island_example.md
@@ -26,8 +26,8 @@
 
 !!! note "Preview"
 
-Islands are an early feature. While the API likely won't change, there are some improvements we'd like to make before we consider them stable.
-Please let us know on [GitHub](https://github.com/marimo-team/marimo/issues) if you run into any issues or have any feedback!
+    Islands are an early feature. While the API likely won't change, there are some improvements we'd like to make before we consider them stable.
+    Please let us know on [GitHub](https://github.com/marimo-team/marimo/issues) if you run into any issues or have any feedback!
 
 > This content below is powered by marimo's reactive runtime. It will become interactive after initializing the marimo runtime.
 

diff --git a/docs/guides/scripts.md b/docs/guides/scripts.md
@@ -16,8 +16,8 @@ the [docs page on CLI args](../api/cli_args.md) to learn more.
 
 !!! note "Producing notebook outputs"
 
-To run as a script while also producing HTML of the notebook outputs, use
+    To run as a script while also producing HTML of the notebook outputs, use
 
-```bash
-marimo export html notebook.py -o notebook.html
-```
+    ```bash
+    marimo export html notebook.py -o notebook.html
+    ```
diff --git a/docs/guides/wasm.md b/docs/guides/wasm.md
@@ -17,21 +17,21 @@ having to install Python on your machine.
 
 !!! note "WASM?"
 
-  marimo-in-the-browser is powered by a technology called
-  [WebAssembly](https://webassembly.org/), or "WASM" for short. Hence the
-  name "WASM notebook".
+    marimo-in-the-browser is powered by a technology called
+    [WebAssembly](https://webassembly.org/), or "WASM" for short. Hence the
+    name "WASM notebook".
 
 !!! note "When should I use WASM notebooks?"
 
-  WASM notebooks are excellent for sharing your work, quickly experimenting with
-  code and models, doing lightweight data exploration, authoring blog posts,
-  tutorials, and educational materials, and even building tools. They are
-  not well-suited for notebooks that do heavy computation.
+    WASM notebooks are excellent for sharing your work, quickly experimenting with
+    code and models, doing lightweight data exploration, authoring blog posts,
+    tutorials, and educational materials, and even building tools. They are
+    not well-suited for notebooks that do heavy computation.
 
 !!! warning "Issues?"
 
-  WASM notebooks are a new feature. If you run into
-  problems, please open a [GitHub issue](https://github.com/marimo-team/marimo/issues).
+    WASM notebooks are a new feature. If you run into
+    problems, please open a [GitHub issue](https://github.com/marimo-team/marimo/issues).
 
 ## Creating and sharing WASM notebooks
 
@@ -48,9 +48,9 @@ tools, available to you at all times and on all devices.
 
 !!! tip "Saving WASM notebooks"
 
-When you save a WASM notebook, a copy of your code is saved to your
-web browser's local storage. When you return to [marimo.app](https://marimo.app),
-the last notebook you worked on will be re-opened.
+    When you save a WASM notebook, a copy of your code is saved to your
+    web browser's local storage. When you return to [marimo.app](https://marimo.app),
+    the last notebook you worked on will be re-opened.
 
 ### Creating shareable permalinks
 

diff --git a/docs/guides/working_with_data/plotting.md b/docs/guides/working_with_data/plotting.md
@@ -20,10 +20,11 @@ selections to Python!
 ## Reactive plots! ⚡
 
 !!! warning "Requirements"
-Reactive plots currently require Altair or Plotly. Install with `pip install
-altair` or `pip install plotly`, depending on which library you are using.
-Selections in plotly are limited to scatter plots, treemaps charts, and sunbursts charts, while Altair supports
-a larger class of plots for selections.
+
+    Reactive plots currently require Altair or Plotly. Install with `pip install
+    altair` or `pip install plotly`, depending on which library you are using.
+    Selections in plotly are limited to scatter plots, treemaps charts, and sunbursts charts, while Altair supports
+    a larger class of plots for selections.
 
 ### Altair
 

diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -82,3 +82,8 @@ figure img {
   border: 1px solid #ebebeb;
   border-radius: 5px;
 }
+
+video {
+  border: 1px solid #ebebeb;
+  border-radius: 5px;
+}
diff --git a/marimo/_plugins/stateless/callout.py b/marimo/_plugins/stateless/callout.py
@@ -21,7 +21,7 @@ def callout(
         kind: The kind of callout (affects styling).
 
     Returns:
-        An HTML object.
+        Html (marimo.Html): An HTML object.
     """
     return Html(
         build_stateless_plugin(

diff --git a/marimo/_plugins/stateless/routes.py b/marimo/_plugins/stateless/routes.py
@@ -42,7 +42,7 @@ class routes(UIElement[str, str]):
             that returns the content to display.
 
     Returns:
-        Html: An Html object.
+        Html (marimo.Html): An Html object.
     """
 
     _name: Final[str] = "marimo-routes"

diff --git a/marimo/_plugins/stateless/sidebar.py b/marimo/_plugins/stateless/sidebar.py
@@ -50,7 +50,7 @@ class sidebar(Html):
         footer (object, optional): The content to display at the bottom of the sidebar.
 
     Returns:
-        Html: An Html object.
+        Html (marimo.Html): An Html object.
     """
 
     def __init__(self, item: object, footer: Optional[object] = None) -> None: