v1 of docs site.

Author: josh-padnick

docs/astro.config.mjs

@@ -13,10 +13,6 @@ export default defineConfig({
 					label: 'Intro',
 					autogenerate: { directory: 'intro' },
 				},
-				{
-					label: 'Setup & installation',
-					autogenerate: { directory: 'setup' },
-				},
 				{
 					label: 'CLI',
 					autogenerate: { directory: 'commands' },

docs/src/content/docs/authoring/blocks/Admonition.md

@@ -2,8 +2,6 @@
 title: <Admonition>
 ---
 
-# `<Admonition>` Block
-
 The `<Admonition>` block creates callout boxes to highlight important information, warnings, notes, or tips. It helps draw the user's attention to critical information in your runbook.
 
 ## Basic Usage

…cs/authoring/blocks/BoilerplateInputs.md …s/authoring/blocks/BoilerplateInputs.mdxdocs/src/content/docs/authoring/blocks/BoilerplateInputs.md renamed to docs/src/content/docs/authoring/blocks/BoilerplateInputs.mdx docs/src/content/docs/authoring/blocks/BoilerplateInputs.md renamed to docs/src/content/docs/authoring/blocks/BoilerplateInputs.mdx

@@ -2,7 +2,7 @@
 title: <BoilerplateInputs>
 ---
 
-# `<BoilerplateInputs>` Block
+import { Aside } from '@astrojs/starlight/components';
 
 The `<BoilerplateInputs>` block creates dynamic web forms based on [Boilerplate](https://github.com/gruntwork-io/boilerplate) variable definitions. It's used to collect user input that can then be used in Commands, Checks, or to generate files from templates.
 
@@ -139,6 +139,10 @@ variables:
 
 ### Structured Map (with Schema)
 
+<Aside type="note">
+This schema declaration is not supported by Boilerplate itself, but is supported by Runbooks.
+</Aside>
+
 Map with predefined fields:
 
 ```yaml
@@ -164,6 +168,10 @@ variables:
 
 ## Validations
 
+<Aside type="note">
+Some Boilerplate validation types are not supported by Runbooks.
+</Aside>
+
 Boilerplate supports various validation types:
 
 ```yaml

docs/src/content/docs/authoring/blocks/BoilerplateTemplate.md

@@ -2,13 +2,16 @@
 title: <BoilerplateTemplate>
 ---
 
-# `<BoilerplateTemplate>` Block
-
-The `<BoilerplateTemplate>` block is an advanced component that renders Boilerplate templates inline without writing files to disk. This is useful for previewing generated content or debugging templates.
+The `<BoilerplateTemplate>` block renders Boilerplate templates inline or allows you to specify templates inline in your runbook. Like `<BoilerplateInputs>`, it uses the Boilerplate engine to generate files, but displays the rendered file directly in the markdown.
 
 ## Overview
 
-While `<BoilerplateInputs>` generates files and saves them to disk, `<BoilerplateTemplate>` renders templates in-memory and displays them in the UI. This is particularly useful when you want to:
+Both `<BoilerplateInputs>` and `<BoilerplateTemplate>` use the Boilerplate engine to generate files. The key differences are:
+
+- **`<BoilerplateInputs>`**: Generates files and saves them to your workspace (persisted), can reference template directories
+- **`<BoilerplateTemplate>`**: Generates files, displays content inline, allows inline template specification
+
+Use `<BoilerplateTemplate>` when you want to:
 
 - Show users a preview of what will be generated
 - Display generated configuration inline
@@ -17,7 +20,7 @@ While `<BoilerplateInputs>` generates files and saves them to disk, `<Boilerplat
 
 ## Basic Usage
 
-```mdx
+`````mdx
 <BoilerplateInputs id="config">
 ```yaml
 variables:
@@ -29,7 +32,7 @@ variables:
     type: int
     description: Port number
     default: 8080
-\```
+```
 </BoilerplateInputs>
 
 <BoilerplateTemplate boilerplateInputsId="config">
@@ -39,9 +42,9 @@ service:
   name: {{ .ServiceName }}
   port: {{ .Port }}
   enabled: true
-\```
-</BoilerplateTemplate>
 ```
+</BoilerplateTemplate>
+`````
 
 ## Props
 
@@ -57,9 +60,10 @@ service:
 ## How It Works
 
 1. User fills out the BoilerplateInputs form
-2. BoilerplateTemplate automatically re-renders the template with the current variable values
-3. Rendered content is displayed in the UI with syntax highlighting
-4. No files are written to disk
+2. BoilerplateTemplate automatically uses the Boilerplate engine to generate files with the current variable values
+3. Files are generated to temporary directories, read for display, then immediately cleaned up
+4. Generated content is displayed in the UI with syntax highlighting
+5. No files are persisted to your workspace (only shown in the UI)
 
 ## Examples
 
@@ -249,10 +253,11 @@ resource "aws_instance" "app" {
 
 | Feature | BoilerplateInputs | BoilerplateTemplate |
 |---------|------------------|---------------------|
-| Generates files | ✅ Yes (to disk) | ❌ No |
-| Shows preview | ❌ No | ✅ Yes |
+| Uses Boilerplate engine | ✅ Yes | ✅ Yes |
+| Generates files | ✅ Yes (persisted to workspace) | ✅ Yes (temporary, cleaned up) |
+| Shows preview in UI | ❌ No | ✅ Yes |
 | Can use with Commands | ✅ Yes | ✅ Yes (variables available) |
-| File tree output | ✅ Yes | ✅ Yes (preview only) |
+| File tree output | ✅ Yes (persisted) | ✅ Yes (preview only) |
 | Template directory | ✅ Supports | ❌ Inline only |
 | Auto-render | ✅ Yes (for Commands/Checks) | ✅ Yes |
 
@@ -309,7 +314,7 @@ Display an entire configuration set:
 ## Limitations
 
 - Templates must be inline (cannot reference template directories like BoilerplateInputs can)
-- Files are not saved to disk
+- Generated files are not persisted to your workspace (only displayed in the UI)
 - Cannot include other template files (no `{{ template "file.txt" }}` support)
 - Best for simple, single-file templates or small sets of templates
 

docs/src/content/docs/authoring/blocks/Check.md

@@ -2,8 +2,6 @@
 title: <Check>
 ---
 
-# `<Check>` Block
-
 The `<Check>` block validates prerequisites and system state by running shell commands or scripts. It's essential for ensuring users have the right tools installed and their environment is properly configured before proceeding.
 
 ## Basic Usage

docs/src/content/docs/authoring/blocks/Command.md

@@ -2,8 +2,6 @@
 title: <Command>
 ---
 
-# `<Command>` Block
-
 The `<Command>` block executes shell commands or scripts with variable substitution. It's used for performing operations like deployments, resource creation, and system configuration.
 
 ## Basic Usage

docs/src/content/docs/authoring/overview.md

@@ -10,7 +10,7 @@ Runbooks are written in **MDX** (Markdown with JSX), which means you can use all
 
 ## File Format
 
-Runbooks use the `.mdx` file extension, though `.md` files with special blocks will also work. The file contains:
+Runbooks must be named `runbook.mdx` and use the MDX file format. The file contains:
 
 1. **Standard Markdown** - Headers, paragraphs, lists, code blocks, images, links, etc.
 2. **Special Blocks** - React components like `<Check>`, `<Command>`, `<BoilerplateInputs>`, etc.

docs/src/content/docs/authoring/workflow.md

@@ -10,7 +10,7 @@ If you're writing runbooks (not developing the Runbooks tool itself), the workfl
 
 ### 1. Create Your Runbook
 
-Create a new `.mdx` file:
+Create a new `runbook.mdx` file:
 
 ```bash
 mkdir my-runbook

docs/src/content/docs/commands/open.md

@@ -0,0 +1,41 @@
+---
+title: open
+---
+
+# `runbooks open`
+
+Opens a runbook in your default browser with the interactive web interface.
+
+## Usage
+
+```bash
+runbooks open <path-to-runbook>
+```
+
+## Arguments
+
+- `<path-to-runbook>` - Path to the `runbook.mdx` file.
+
+## What It Does
+
+When you run `runbooks open`:
+
+1. **Starts the Backend Server** - Launches a Go-based HTTP server on port 7825
+2. **Launches the Browser** - Opens your default web browser to `http://localhost:7825`
+3. **Serves the Frontend** - The web UI connects to the backend API to process the runbook
+4. **Keeps Running** - The server continues running until you close the browser or press Ctrl+C
+
+## Troubleshooting
+
+**Port already in use:**
+If port 7825 is already in use, you'll see an error. Stop any other process using that port or modify the code to use a different port.
+
+**Browser doesn't open:**
+If the browser doesn't open automatically, you can manually navigate to `http://localhost:7825` after running the command.
+
+**Browser window with the runbook doesn't open:**
+Sometimes, your browser seems to launch, but you don't see the Runbook. The most likely issue here is that your browser launched with multiple tabs and windows and your Runbooks tab is not visible. Either look through all your browser windows, or go directly to http://localhost:7825.
+
+**Runbook not found:**
+Make sure the path points to a valid `runbook.mdx` file.
+