More docs updates

README.md

@@ -1,19 +1,27 @@
-# Gruntwork Runbooks
+<p align="center">
+  <a href="https://runbooks.gruntwork.io">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="./web/public/runbooks-logo-light-color.svg" height="80">
+      <source media="(prefers-color-scheme: light)" srcset="./web/public/runbooks-logo-dark-color.svg" height="80">
+      <img alt="Gruntwork Runbooks" src="./web/public/runbooks-logo-dark-color.svg" height="80">
+    </picture>
+  </a>
+</p>
 
-_Make the knowledge and experience of the few available to the many._
+<p align="center"><em>Runbooks enables infrastructure experts to scale their expertise.</em></p>
 
-Runbooks are interactive markdown documents with a first-class experience for generating files based on custom configurations, running customizable scripts or commands, and validating assertions about their local system or infrastructure.
+Runbooks are interactive markdown documents that enable subject matter experts to capture their knowledge and expertise in a way that is easy for others to understand and use.
 
-For additional information on Runbooks, or to see them in action, check out the [Runbooks docs](https://runbooks.gruntwork.io).
+For additional information on Runbooks, or to see it in action, check out the [Runbooks docs](https://runbooks.gruntwork.io).
 
 ## Project status
 
 > [!NOTE]
-> As of October 2025, Runbooks was written by a single author and has not yet had a thorough peer review. GitHub issues identifying issues and pull requests fixing them are welcome!
+> As of December 2025, Runbooks was written by a single author and has not yet had a thorough peer review. GitHub issues identifying issues and pull requests fixing them are welcome!
 
 ## Security concerns
 
-Runbooks are designed to streamline the code generation and commands you might otherwise run on your local computer. This has important security implications you should be aware of prior to running Runbooks.
+Runbooks is designed to streamline the code generation and commands you might otherwise run on your local computer. This has important security implications you should be aware of prior to running Runbooks.
 
 ### Command execution
 
@@ -25,23 +33,6 @@ If you do not trust a Runbook file or you're not sure about the author or origin
 
 Runbooks executes commands when the Runbooks frontend makes API calls the Runbooks backend. Runbooks takes various [security measures](http://runbooks.gruntwork.io/security/execution-model/) to make sure that only commands and scripts that are part of the Runbook can be executed via this API, however there are some modes where these restrictions are relaxed in favor of more convenience. Read the docs to understand the security posture in more depth.
 
-## Read the docs
-
-For now, you'll need to manually launch the docs site by doing the following:
-
-1. Install [Bun](https://bun.sh/docs/installation)
-
-   Bun is a fast JavaScript runtime and package manager that works out of the box.
-
-1. Git clone this repo and `cd` to the repo dir.
-
-1. Start Vite to run the React frontend:
-   ```bash
-   cd docs
-   bun install
-   bun dev
-   ```
-
 ## Building
 
 This project uses [Task](https://taskfile.dev/) as a task runner. Install it first:

docs/astro.config.mjs

@@ -57,10 +57,12 @@ export default defineConfig({
 				collapsed: true,
 				items: [
 					'authoring/overview',
-					'authoring/authoring_workflow',
+					'authoring/runbook-structure',
 					'authoring/markdown',
+					'authoring/variables',
+					'authoring/boilerplate',
 					{
-						label: 'Blocks', // Customize this to whatever you want
+						label: 'Blocks',
 						autogenerate: { directory: 'authoring/blocks' },
 					},
 				],

docs/cspell.json

@@ -0,0 +1,48 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "words": [
+    "runbook",
+    "runbooks",
+    "Gruntwork",
+    "Blockquotes",
+    "Strikethrough",
+    "bunx",
+    "elif",
+    "fsnotify",
+    "LOCALAPPDATA",
+    "mozallowfullscreen",
+    "webkitallowfullscreen",
+    "myapp",
+    "prereq",
+    "pyenv",
+    "scaffolder",
+    "sysdm",
+    "testdata",
+    "astro",
+    "starlight",
+    "boilerplate",
+    "templating",
+    "mdx",
+    "tofu",
+    "opentofu",
+    "devops",
+    "infra",
+    "homebrew",
+    "kubectl",
+    "terraform",
+    "terragrunt",
+    "pipelining"
+  ],
+  "ignorePaths": [
+    "node_modules",
+    "dist",
+    "bun.lock",
+    "*.svg"
+  ],
+  "ignoreRegExpList": [
+    "/```[\\s\\S]*?```/g",
+    "/<[^>]+>/g"
+  ]
+}
+

docs/package.json

@@ -8,12 +8,17 @@
     "prebuild": "cd ../testdata && zip -r ../docs/public/my-first-runbook.zip my-first-runbook",
     "build": "astro build",
     "preview": "astro preview",
-    "astro": "astro"
+    "astro": "astro",
+    "spellcheck": "cspell \"src/content/**/*.{md,mdx}\" --no-progress",
+    "spellcheck:fix": "cspell \"src/content/**/*.{md,mdx}\" --no-progress --show-suggestions"
   },
   "dependencies": {
     "@astrojs/starlight": "^0.36.0",
     "@vercel/analytics": "^1.5.0",
     "astro": "^5.6.1",
     "sharp": "^0.34.2"
+  },
+  "devDependencies": {
+    "cspell": "^9.4.0"
   }
 }

docs/src/components/Head.astro

@@ -10,3 +10,37 @@ import Analytics from '@vercel/analytics/astro';
 <link rel="icon" href="/favicon-dark.svg" type="image/svg+xml" media="(prefers-color-scheme: dark)" />
 <Analytics />
 
+<!-- Replace Terraform icons with OpenTofu icons in FileTree for .tf files -->
+<script>
+  // OpenTofu logo SVG path (official logo simplified for 24x24 viewBox)
+  const opentofuPath = `
+    <path d="M12 2L3 7v10l9 5 9-5V7l-9-5zm0 2.18l6.26 3.48L12 11.14 5.74 7.66 12 4.18zm-7 5.04l6 3.33v6.63l-6-3.33v-6.63zm8 9.96v-6.63l6-3.33v6.63l-6 3.33z" fill="currentColor"/>
+  `;
+
+  function replaceTerraformIconsWithOpenTofu() {
+    document.querySelectorAll('starlight-file-tree').forEach(tree => {
+      tree.querySelectorAll('.file .tree-entry').forEach(entry => {
+        const text = entry.textContent || '';
+        // Check if this is a .tf, .tfvars, or .tf.json file
+        if (text.match(/\.tf($|\s|\.json)|\.tfvars/)) {
+          const svg = entry.querySelector('svg.tree-icon');
+          if (svg) {
+            svg.innerHTML = opentofuPath;
+            svg.setAttribute('viewBox', '0 0 24 24');
+          }
+        }
+      });
+    });
+  }
+
+  // Run when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', replaceTerraformIconsWithOpenTofu);
+  } else {
+    replaceTerraformIconsWithOpenTofu();
+  }
+
+  // Also run after Astro page transitions (for view transitions)
+  document.addEventListener('astro:page-load', replaceTerraformIconsWithOpenTofu);
+</script>
+

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

@@ -24,12 +24,10 @@ The `<Admonition>` block creates callout boxes to highlight important informatio
 
 - `title` (string) - Title for the callout box (defaults based on type)
 - `description` (string) - Content/message to display
-- `children` (ReactNode) - Alternative to description for more complex content
 - `closable` (boolean) - Whether users can close the admonition (default: false)
 - `confirmationText` (string) - If provided, shows a checkbox that users must check to dismiss
 - `allowPermanentHide` (boolean) - When true with confirmationText, adds "Don't show again" option
 - `storageKey` (string) - Unique key for localStorage (required with allowPermanentHide)
-- `className` (string) - Additional CSS classes
 
 ## Types
 
@@ -81,9 +79,9 @@ For critical warnings or errors:
 />
 ```
 
-## With Children
+## Inline content
 
-Instead of using the `description` prop, you can provide richer content as children:
+Instead of using the `description` prop, you can provide richer content inline:
 
 ```mdx
 <Admonition type="info" title="Prerequisites">