docs: tweak styles

11 files changed, 52 insertions, 18 deletions

diff --git a/bun.lock b/bun.lock
index 5457a1408..a14065e07 100644
--- a/bun.lock
+++ b/bun.lock
@@ -82,7 +82,7 @@
         "sharp": "0.32.5",
         "shiki": "3.4.2",
         "solid-js": "1.9.7",
-        "toolbeam-docs-theme": "0.3.0",
+        "toolbeam-docs-theme": "0.4.1",
       },
       "devDependencies": {
         "@types/node": "catalog:",
@@ -1546,7 +1546,7 @@
 
     "token-types": ["[email protected]", "", { "dependencies": { "@tokenizer/token": "^0.3.0", "ieee754": "^1.2.1" } }, "sha512-lbDrTLVsHhOMljPscd0yitpozq7Ga2M5Cvez5AjGg8GASBjtt6iERCAJ93yommPmz62fb45oFIXHEZ3u9bfJEA=="],
 
-    "toolbeam-docs-theme": ["[email protected]", "", { "peerDependencies": { "@astrojs/starlight": "^0.34.3", "astro": "^5.7.13" } }, "sha512-qlBkKRp8HVYV7p7jaG9lT2lvQY7c8b9czZ0tnsJUrN2TBTtEyFJymCdkhhpZNC9U4oGZ7lLk0glRJHrndWvVsg=="],
+    "toolbeam-docs-theme": ["[email protected]", "", { "peerDependencies": { "@astrojs/starlight": "^0.34.3", "astro": "^5.7.13" } }, "sha512-lTI4dHZaVNQky29m7sb36Oy4tWPwxsCuFxFjF8hgGW0vpV+S6qPvI9SwsJFvdE/OHO5DoI7VMbryV1pxZHkkHQ=="],
 
     "tr46": ["[email protected]", "", {}, "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="],
 
diff --git a/packages/web/package.json b/packages/web/package.json
index 2d69de272..383b979fa 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -28,7 +28,7 @@
     "sharp": "0.32.5",
     "shiki": "3.4.2",
     "solid-js": "1.9.7",
-    "toolbeam-docs-theme": "0.3.0"
+    "toolbeam-docs-theme": "0.4.1"
   },
   "devDependencies": {
     "opencode": "workspace:*",
diff --git a/packages/web/src/components/Head.astro b/packages/web/src/components/Head.astro
index 36f11c955..3d9bc0f53 100644
--- a/packages/web/src/components/Head.astro
+++ b/packages/web/src/components/Head.astro
@@ -7,13 +7,14 @@ import config from '../../config.mjs'
 const slug = Astro.url.pathname.replace(/^\//, "").replace(/\/$/, "");
 const {
   entry: {
-    data: { title },
+    data: { title , description },
   },
 } = Astro.locals.starlightRoute;
 const isDocs = slug.startsWith("docs")
 
 let encodedTitle = '';
 let ogImage = `${config.url}/social-share.png`;
+let truncatedDesc = '';
 
 if (isDocs) {
   // Truncate to fit S3's max key size
@@ -26,7 +27,12 @@ if (isDocs) {
       )
     )
   );
-  ogImage = `${config.socialCard}/opencode-docs/${encodedTitle}.png`;
+
+  if (description) {
+    truncatedDesc = encodeURIComponent(description.substring(0, 400))
+  }
+
+  ogImage = `${config.socialCard}/opencode-docs/${encodedTitle}.png?desc=${truncatedDesc}`;
 }
 ---
 
diff --git a/packages/web/src/content/docs/docs/cli.mdx b/packages/web/src/content/docs/docs/cli.mdx
index a7758d21e..49d343bee 100644
--- a/packages/web/src/content/docs/docs/cli.mdx
+++ b/packages/web/src/content/docs/docs/cli.mdx
@@ -1,5 +1,6 @@
 ---
 title: CLI
+description: The opencode CLI options and commands.
 ---
 
 Running the opencode CLI starts it for the current directory.
@@ -20,6 +21,8 @@ opencode /path/to/project
 
 The opencode CLI also has the following commands.
 
+---
+
 ### run
 
 Run opencode in non-interactive mode by passing a prompt directly.
@@ -53,6 +56,8 @@ Command to manage credentials and login for providers.
 opencode auth [command]
 ```
 
+---
+
 #### login
 
 Logs you into a provider and saves them in the credentials file in `~/.local/share/opencode/auth.json`.
@@ -63,6 +68,8 @@ opencode auth login
 
 When opencode starts up it will loads the providers from the credentials file. And if there are any keys defined in your environments or a `.env` file in your project.
 
+---
+
 #### list
 
 Lists all the authenticated providers as stored in the credentials file.
@@ -77,6 +84,8 @@ Or the short version.
 opencode auth ls
 ```
 
+---
+
 #### logout
 
 Logs you out of a provider by clearing it from the credentials file.
diff --git a/packages/web/src/content/docs/docs/config.mdx b/packages/web/src/content/docs/docs/config.mdx
index e9a493afc..d88749c62 100644
--- a/packages/web/src/content/docs/docs/config.mdx
+++ b/packages/web/src/content/docs/docs/config.mdx
@@ -1,5 +1,6 @@
 ---
 title: Config
+description: Using the opencode JSON config.
 ---
 
 You can configure opencode using a JSON config file that can be placed in:
diff --git a/packages/web/src/content/docs/docs/index.mdx b/packages/web/src/content/docs/docs/index.mdx
index 4926450c7..b39ce452c 100644
--- a/packages/web/src/content/docs/docs/index.mdx
+++ b/packages/web/src/content/docs/docs/index.mdx
@@ -1,5 +1,6 @@
 ---
 title: Intro
+description: Get started with opencode.
 ---
 
 import { Tabs, TabItem } from '@astrojs/starlight/components';
@@ -62,12 +63,12 @@ brew install sst/tap/opencode
 paru -S opencode-bin
 ```
 
----
-
 ##### Windows
 
 Right now the automatic installation methods do not work properly on Windows. However you can grab the binary from the [Releases](https://github.com/sst/opencode/releases).
 
+---
+
 ## Providers
 
 We recommend signing up for Claude Pro or Max, running `opencode auth login` and selecting Anthropic. It's the most cost-effective way to use opencode.
diff --git a/packages/web/src/content/docs/docs/keybinds.mdx b/packages/web/src/content/docs/docs/keybinds.mdx
index ba18fd25c..8c5aa2c42 100644
--- a/packages/web/src/content/docs/docs/keybinds.mdx
+++ b/packages/web/src/content/docs/docs/keybinds.mdx
@@ -1,5 +1,6 @@
 ---
 title: Keybinds
+description: Customize your keybinds.
 ---
 
 opencode has a list of keybinds that you can customize through the opencode config.
diff --git a/packages/web/src/content/docs/docs/mcp-servers.mdx b/packages/web/src/content/docs/docs/mcp-servers.mdx
index d34a1ac41..72c33e8ad 100644
--- a/packages/web/src/content/docs/docs/mcp-servers.mdx
+++ b/packages/web/src/content/docs/docs/mcp-servers.mdx
@@ -1,5 +1,6 @@
 ---
 title: MCP servers
+description: Add local and remote MCP tools.
 ---
 
 You can add external tools to opencode using the _Model Context Protocol_, or MCP. opencode supports both:
diff --git a/packages/web/src/content/docs/docs/models.mdx b/packages/web/src/content/docs/docs/models.mdx
index 28a22dd4e..f60a25442 100644
--- a/packages/web/src/content/docs/docs/models.mdx
+++ b/packages/web/src/content/docs/docs/models.mdx
@@ -1,5 +1,6 @@
 ---
 title: Models
+description: Configuring an LLM provider and model.
 ---
 
 opencode uses the [AI SDK](https://ai-sdk.dev/) and [Models.dev](https://models.dev) to support for **75+ LLM providers** and it supports running local models.
diff --git a/packages/web/src/content/docs/docs/rules.mdx b/packages/web/src/content/docs/docs/rules.mdx
index c02ce50fc..aed085352 100644
--- a/packages/web/src/content/docs/docs/rules.mdx
+++ b/packages/web/src/content/docs/docs/rules.mdx
@@ -1,5 +1,6 @@
 ---
 title: Rules
+description: Set custom instructions for opencode.
 ---
 
 You can provide custom instructions to opencode by creating an `AGENTS.md` file. This is similar to `CLAUDE.md` or Cursor's rules. It contains instructions that will be included in the LLM's context to customize its behavior for your specific project.
diff --git a/packages/web/src/content/docs/docs/themes.mdx b/packages/web/src/content/docs/docs/themes.mdx
index 42f4edcee..da612284e 100644
--- a/packages/web/src/content/docs/docs/themes.mdx
+++ b/packages/web/src/content/docs/docs/themes.mdx
@@ -1,5 +1,6 @@
 ---
 title: Themes
+description: Select a built-in theme or define your own.
 ---
 
 With opencode you can select from one of several built-in themes, use a theme that adapts to your terminal theme, or define your own custom theme.
@@ -62,6 +63,8 @@ You can select a theme by bringing up the theme select with the `/theme` command
 
 opencode supports a flexible JSON-based theme system that allows users to create and customize themes easily. 
 
+---
+
 ### Hierarchy
 
 Themes are loaded from multiple directories in the following order where later directories override earlier ones:
@@ -73,6 +76,8 @@ Themes are loaded from multiple directories in the following order where later d
 
 If multiple directories contain a theme with the same name, the theme from the directory with higher priority will be used.
 
+---
+
 ### Creating a theme
 
 To create a custom theme, create a JSON file in one of the theme directories.
@@ -91,6 +96,8 @@ mkdir -p .opencode/themes
 vim .opencode/themes/my-theme.json
 ```
 
+---
+
 ### JSON format
 
 Themes use a flexible JSON format with support for:
@@ -101,6 +108,23 @@ Themes use a flexible JSON format with support for:
 - **Dark/light variants**: `{"dark": "#000", "light": "#fff"}`
 - **No color**: `"none"` - Uses the terminal's default color or transparent
 
+---
+
+### Color definitions
+
+The `defs` section is optional and it allows you to define reusable colors that can be referenced in the theme.
+
+---
+
+### Terminal defaults
+
+The special value `"none"` can be used for any color to inherit the terminal's default color. This is particularly useful for creating themes that blend seamlessly with your terminal's color scheme:
+
+- `"text": "none"` - Uses terminal's default foreground color
+- `"background": "none"` - Uses terminal's default background color
+
+---
+
 ### Example
 
 Here's an example of a custom theme:
@@ -330,14 +354,3 @@ Here's an example of a custom theme:
   }
 }
 ```
-
-### Color definitions
-
-The `defs` section is optional and it allows you to define reusable colors that can be referenced in the theme.
-
-### Terminal defaults
-
-The special value `\"none\"` can be used for any color to inherit the terminal's default color. This is particularly useful for creating themes that blend seamlessly with your terminal's color scheme:
-
-- `"text": "none"` - Uses terminal's default foreground color
-- `"background": "none"` - Uses terminal's default background color