docs: guide > get-started

web/_quarto.yml

@@ -11,6 +11,7 @@ website:
   site-url: https://quarto-gradio.peter.gy
   repo-url: https://github.com/peter-gy/quarto-gradio
   page-navigation: true
+  back-to-top-navigation: false
   bread-crumbs: true
 
   search:
@@ -131,7 +132,8 @@ website:
   page-footer:
     background: dark
     border: true
-    left: "Created by Péter Ferenc Gyarmati"
+    left: |
+      Made by [Péter Ferenc Gyarmati](https://peter.gy) · Powered by [Quarto](https://quarto.org)<sup>®</sup>
     right: 
       - icon: github
         href: https://l.peter.gy/github
@@ -153,11 +155,14 @@ format:
           <script defer src="https://umami.peter.gy/script.js" data-website-id="6da82a32-91fa-4705-9038-888abf4cdcd8"></script>
     grid:
       sidebar-width: 300px
-      body-width: 1100px
-      margin-width: 0px
+      body-width: 800px
+      margin-width: 200px
 
 filters:
   - gradio
 
+shortcodes:
+  - tools/src-include.lua
+
 execute:
   enabled: false

web/guide/get-started/hello-world.qmd

@@ -0,0 +1,21 @@
+---
+filters:
+  - gradio
+---
+
+```{python}
+import gradio as gr
+
+def greet(name):
+    return f"Hello {name}!"
+
+
+demo = gr.Interface(
+    fn=greet,
+    inputs="textbox",
+    outputs="textbox",
+    live=True
+)
+
+demo.launch()
+```

web/guide/get-started/index.qmd

@@ -1,7 +1,12 @@
 ---
 title: "🚀 Get Started"
+format:
+  html:
+    toc: true
 ---
 
+This guide will help you get started with the `quarto-gradio` extension via a simple example. You will see how you can iterate on your Gradio app's source code in your local environment, then embed the very same app with no changes into an entirely browser-based environment.
+
 ## Installation
 
 First things first, make sure you have the `quarto-gradio` extension installed:
@@ -10,16 +15,39 @@ First things first, make sure you have the `quarto-gradio` extension installed:
 quarto add peter-gy/quarto-gradio
 ```
 
-Ans also ensure that you have an active Python environment with `gradio` installed:
-
-```bash
-pip install gradio
-```
+This will allow us to use the `gradio` filter in our Quarto documents.
 
 ## Hello World
 
-```` md
-{{< include ../examples/hello-world.qmd >}}
+We will get started with a simple "Hello World" example written in a `qmd` document.
+
+### Source Code
+
+We register the `gradio` filter in the document's YAML header and we define a simple Python code block with a basic Gradio interface.
+
+````md
+{{< src-include hello-world.qmd >}}
 ````
 
-<iframe src="/guide/examples/hello-world.html" width="100%" height="400px"></iframe>
+### Local Execution
+
+Since this is a plain old Python program, it can be executed directly in an interactive Python session using your local, serverful Python interpreter.
+
+![Executing the "Hello World" example directly in a local Python session spawned using the "Run Cell" button of the Quarto VSCode extension.](../../public/hello-world-run-cell.gif)
+
+### Browser Execution
+
+However, thanks to the `gradio` filter, after rendering the document, you can access the very same interface directly from your browser, blending with the theme you have specified. In fact, you can see the example embedded into *this* document right below.
+
+{{< include hello-world.qmd >}}
+
+:::{.callout-tip}
+As you can see, the Gradio interface is fully interactive without a Python server.
+The `gradio` filter also made sure that the Gradio app's CSS is harmonized with your current HTML theme.
+:::
+
+## Next Steps
+
+Sometimes you may want to let users to experiment with and modify the Gradio app's source code directly in their browser, seeing changes reflected instantly.
+
+In the next section, we'll explore how to enable just that in an interactive coding playground that lets users edit and run Python code without needing to re-render the document.

web/tools/src-include.lua

@@ -0,0 +1,25 @@
+function src_include_shortcode(args, kwargs)
+    -- Get the file path from the first argument
+    local file_path = args[1]
+    if not file_path then
+        io.stderr:write("Warning: No file path provided to src-include\n")
+        return pandoc.Null()
+    end
+
+    -- Read the file contents
+    local file, err = io.open(file_path, "r")
+    if not file then
+        io.stderr:write("Warning: Could not open file: " .. file_path .. (err and (" - " .. err) or "") .. "\n")
+        return pandoc.Null()
+    end
+
+    -- Read the entire file content
+    local content = file:read("*all")
+    file:close()
+
+    return pandoc.Code(content)
+end
+
+return {
+    ['src-include'] = src_include_shortcode
+}