chore(docs): improve headers (#22)

yzuyr · web-flow · commit b80f988b8b89 · 2026-04-23T16:31:17.000+02:00
* chore(docs): improve headers

* fix(pr): improvements

* chore(docs): add descriptions
diff --git a/apps/website/docs/guide/getting-started/core-concepts.md b/apps/website/docs/guide/getting-started/core-concepts.md
@@ -1,7 +1,10 @@
 ---
 title: Core Concepts
+description: Learn the core ideas behind ilha — islands, signals, HTML-first rendering, and the builder chain.
 ---
 
+# Core Concepts
+
 ilha is built around a small set of ideas: islands, signals, HTML-first rendering, and a builder-based API. Once these click, the rest of the library feels straightforward.
 
 ## Islands
diff --git a/apps/website/docs/guide/getting-started/installation.mdx b/apps/website/docs/guide/getting-started/installation.mdx
@@ -1,7 +1,10 @@
 ---
 title: Installation
+description: Install ilha and start building with official templates for Vite, Hono, Nitro, Elysia, and Electrobun.
 ---
 
+# Installation
+
 import { PackageManagerTabs } from "@rspress/core/theme";
 
 ilha can be installed with your package manager of choice.
diff --git a/apps/website/docs/guide/getting-started/introduction.md b/apps/website/docs/guide/getting-started/introduction.md
@@ -1,7 +1,10 @@
 ---
 title: Introduction
+description: An introduction to ilha, a tiny isomorphic island framework with fine-grained signal reactivity.
 ---
 
+# Introduction
+
 ilha is a tiny, isomorphic island framework for building reactive UI components.
 
 It lets you render on the server and mount in the browser with fine-grained signal reactivity, without a virtual DOM or compiler overhead. The result is a UI model that stays close to HTML, but still gives you state, events, lifecycle hooks, scoped styles, and hydration when you need them.
diff --git a/apps/website/docs/guide/helpers/context.md b/apps/website/docs/guide/helpers/context.md
@@ -1,7 +1,10 @@
 ---
 title: context()
+description: Create named global signals to share reactive state across islands without prop drilling.
 ---
 
+# Context
+
 Creates a named global signal shared across all islands. Identical keys always return the same signal instance, making it the primary way to share reactive state between islands without prop drilling or a separate store.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/helpers/css.md b/apps/website/docs/guide/helpers/css.md
@@ -1,7 +1,10 @@
 ---
 title: css&grave;&grave;
+description: A passthrough tagged template for CSS strings that enables editor tooling and syntax highlighting.
 ---
 
+# CSS
+
 A passthrough tagged template for CSS strings. It has no runtime effect — its sole purpose is to tell editors and language tools that the content is CSS, enabling syntax highlighting, autocompletion, and formatting.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/helpers/html.md b/apps/website/docs/guide/helpers/html.md
@@ -1,7 +1,10 @@
 ---
 title: html&grave;&grave;
+description: An XSS-safe tagged template for building HTML strings with automatic escaping and signal interpolation.
 ---
 
+# HTML
+
 An XSS-safe tagged template for building HTML strings. Interpolated values are HTML-escaped by default, making the safe path the default and explicit opt-in required for raw markup.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/helpers/mount.md b/apps/website/docs/guide/helpers/mount.md
@@ -1,7 +1,10 @@
 ---
 title: mount()
+description: Auto-discover and mount ilha islands from the DOM, with support for lazy loading and hydration.
 ---
 
+# Mount
+
 Auto-discovers all `[data-ilha]` elements in the DOM and mounts the matching island from a registry. This is the recommended way to activate islands on a page, especially when using SSR and hydration.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/helpers/raw.md b/apps/website/docs/guide/helpers/raw.md
@@ -1,7 +1,10 @@
 ---
 title: raw()
+description: Mark strings as trusted HTML to bypass escaping inside html`` templates.
 ---
 
+# Raw
+
 Marks a string as trusted HTML, bypassing escaping when interpolated inside [`html`](/guide/helpers/html). Use it when you need to inject markup you fully control — icons, pre-rendered fragments, or server-sanitized content.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/bind.md b/apps/website/docs/guide/island/bind.md
@@ -1,7 +1,10 @@
 ---
 title: .bind()
+description: Two-way bind form elements to state keys or external signals with automatic type coercion.
 ---
 
+# Bind
+
 Two-way binds a form element to a state key or external signal. When the state changes, the element updates. When the user interacts with the element, the state updates.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/css.md b/apps/website/docs/guide/island/css.md
@@ -1,7 +1,10 @@
 ---
 title: .css()
+description: Attach scoped styles to an island using CSS @scope rules that stay local and do not leak.
 ---
 
+# CSS
+
 Attaches scoped styles to the island. Styles are automatically wrapped in a `@scope` rule bounded to the island host, so they apply only within the island and do not leak into child islands.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/derived.md b/apps/website/docs/guide/island/derived.md
@@ -1,7 +1,10 @@
 ---
 title: .derived()
+description: Declare computed values that depend on state or input, with built-in loading and error envelopes.
 ---
 
+# Derived
+
 Declares a computed value that depends on state or input. Derived values can be synchronous or async, and they re-run automatically when any reactive dependency changes.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/effect.md b/apps/website/docs/guide/island/effect.md
@@ -1,7 +1,10 @@
 ---
 title: .effect()
+description: Register reactive side effects that run after mount and re-run when signal dependencies change.
 ---
 
+# Effect
+
 Registers a reactive side effect that runs after the island mounts and re-runs automatically whenever any signal it reads changes. Use it to sync state to the outside world — the DOM, browser APIs, timers, or external systems.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/hydratable.md b/apps/website/docs/guide/island/hydratable.md
@@ -1,7 +1,10 @@
 ---
 title: .hydratable()
+description: Render islands wrapped in hydration containers with serialized props and optional state snapshots.
 ---
 
+# Hydratable
+
 Renders the island wrapped in a hydration container. The output includes everything `ilha.mount()` needs to activate the island on the client — the rendered HTML, serialized props, and optionally a state snapshot — all embedded as data attributes on a wrapper element.
 
 Use this method in your SSR handler whenever you want the island to become interactive in the browser without a full client-side re-render.
diff --git a/apps/website/docs/guide/island/input.md b/apps/website/docs/guide/island/input.md
@@ -1,7 +1,10 @@
 ---
 title: .input()
+description: Declare typed external props with optional Standard Schema runtime validation and coercion.
 ---
 
+# Input
+
 Declares the island's external props and their types. Two forms are supported: a type-only generic for when you just need TypeScript inference, and a [Standard Schema](https://standardschema.dev/)-compatible validator (Zod, Valibot, ArkType, etc.) for runtime validation too.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/on.md b/apps/website/docs/guide/island/on.md
@@ -1,7 +1,10 @@
 ---
 title: .on()
+description: Attach DOM event listeners to island hosts or descendant elements with selector syntax and modifiers.
 ---
 
+# On
+
 Attaches a DOM event listener to the island host or any descendant element. Listeners are set up at mount time and cleaned up automatically on unmount.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/onmount.md b/apps/website/docs/guide/island/onmount.md
@@ -1,7 +1,10 @@
 ---
 title: .onMount()
+description: Register one-time setup functions that run after an island is mounted into the DOM.
 ---
 
+# onMount
+
 Registers a function that runs once after the island is mounted into the DOM. Use it for one-time setup that needs access to the host element, such as initializing third-party libraries, measuring layout, or setting up manual DOM integrations.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/render.md b/apps/website/docs/guide/island/render.md
@@ -1,7 +1,10 @@
 ---
 title: .render()
+description: Finalize the builder chain and produce a callable island that can render to HTML or mount in the browser.
 ---
 
+# Render
+
 Finalizes the builder chain and returns a callable `Island`. This is always the last method in the chain — every other builder method must be called before `.render()`.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/slot.md b/apps/website/docs/guide/island/slot.md
@@ -1,7 +1,10 @@
 ---
 title: .slot()
+description: Embed child islands as named slots inside a parent, rendered inline during SSR and activated independently.
 ---
 
+# Slot
+
 Embeds a child island as a named slot inside a parent island. The child is rendered inline during SSR and activated independently on the client. Each slot is managed as its own island — it owns its own state, lifecycle, and reactivity.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/state.md b/apps/website/docs/guide/island/state.md
@@ -1,7 +1,10 @@
 ---
 title: .state()
+description: Declare reactive signals local to an island to store values that change over time and drive re-renders.
 ---
 
+# State
+
 Declares a reactive signal local to the island. State is the primary way to store values that change over time and drive re-renders.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/island/transition.md b/apps/website/docs/guide/island/transition.md
@@ -1,7 +1,10 @@
 ---
 title: .transition()
+description: Attach enter and leave animation callbacks to islands for async mount and unmount transitions.
 ---
 
+# Transition
+
 Attaches enter and leave animation callbacks to the island. The enter callback runs when the island mounts, and the leave callback runs when it unmounts. Both are async — ilha awaits the leave transition before tearing down the island.
 
 ## Basic usage
diff --git a/apps/website/docs/guide/libraries/form.mdx b/apps/website/docs/guide/libraries/form.mdx
@@ -1,7 +1,10 @@
 ---
 title: "@ilha/form"
+description: A typed form binding library for ilha islands with Standard Schema validation and native DOM events.
 ---
 
+# Ilha Form
+
 import { PackageManagerTabs } from "@rspress/core/theme";
 
 `@ilha/form` is a tiny, typed form binding library for ilha islands. It connects a Standard Schema validator to a native `<form>` and gives you typed submit handling, per-field errors, dirty state, default values, and DOM-based validation — no runtime dependencies beyond your chosen schema library.
diff --git a/apps/website/docs/guide/libraries/router.mdx b/apps/website/docs/guide/libraries/router.mdx
@@ -1,7 +1,10 @@
 ---
 title: "@ilha/router"
+description: A lightweight isomorphic router for ilha apps with file-system routing, loaders, and SPA navigation.
 ---
 
+# Ilha Router
+
 import { PackageManagerTabs } from "@rspress/core/theme";
 
 `@ilha/router` is a lightweight, isomorphic router for ilha apps. It runs on the server as a synchronous HTML renderer and in the browser with full signal-driven reactivity. It is a separate package — not bundled with `ilha` — so you only pay for it when you need multi-page routing.
diff --git a/apps/website/docs/guide/libraries/store.mdx b/apps/website/docs/guide/libraries/store.mdx
@@ -1,7 +1,10 @@
 ---
 title: "@ilha/store"
+description: A zustand-shaped reactive store for shared global state backed by alien-signals.
 ---
 
+# Ilha Store
+
 import { PackageManagerTabs } from "@rspress/core/theme";
 
 `@ilha/store` is a zustand-shaped reactive store for ilha apps. It lives outside any island and is backed by [alien-signals](https://github.com/stackblitz/alien-signals) — the same engine that powers ilha core state — so stores and islands share a single reactive graph with no extra bridging.
diff --git a/apps/website/docs/guide/resources/showcase.mdx b/apps/website/docs/guide/resources/showcase.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: Showcase
+description: A collection of websites and projects built with ilha.
 ---
 
 export const SHOWCASE = [
@@ -17,10 +18,12 @@ export const SHOWCASE = [
   },
 ];
 
-<div class="rp-not-doc grid grid-cols-3 gap-4">
+# Showcase
+
+<div className="rp-not-doc grid grid-cols-3 gap-4">
   {SHOWCASE.map((item) => (
-    <div class="card pt-0 overflow-hidden">
-      <img loading="lazy" class="aspect-video object-cover" src={item.image} />
+    <div key={item.title} className="card pt-0 overflow-hidden">
+      <img loading="lazy" className="aspect-video object-cover" src={item.image} />
       <header>
         <h2>
           <a href={item.link} target="_blank" rel="noopener noreferrer" className="underline">
diff --git a/apps/website/docs/index.tsx b/apps/website/docs/index.tsx
@@ -335,6 +335,9 @@ const Heading = ilha
 
 export const frontmatter = {
   pageType: "custom",
+  title: "Build Modern UI, Your Way",
+  description:
+    "Ilha is a lightweight UI framework under 1,500 lines of code. Simple enough to fit in a single AI context window, powerful enough to build modern interfaces your way.",
 };
 
 const hero = await Hero.hydratable({}, { name: "Hero", snapshot: true });
diff --git a/apps/website/docs/public/og.jpg b/apps/website/docs/public/og.jpg
diff --git a/apps/website/docs/tutorial/counter/bind.mdx b/apps/website/docs/tutorial/counter/bind.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: .bind()
+description: Tutorial — two-way bind form elements to state with the .bind() builder method.
 ---
 
 import dedent from "dedent";
diff --git a/apps/website/docs/tutorial/counter/derived.mdx b/apps/website/docs/tutorial/counter/derived.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: .derived()
+description: Tutorial — compute values from state automatically with the .derived() builder method.
 ---
 
 import dedent from "dedent";
diff --git a/apps/website/docs/tutorial/counter/effect.mdx b/apps/website/docs/tutorial/counter/effect.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: .effect()
+description: Tutorial — run reactive side effects whenever state changes with the .effect() builder method.
 ---
 
 import dedent from "dedent";
diff --git a/apps/website/docs/tutorial/counter/on.mdx b/apps/website/docs/tutorial/counter/on.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: .on()
+description: Tutorial — attach event listeners to elements inside your component with the .on() builder method.
 ---
 
 import dedent from "dedent";
diff --git a/apps/website/docs/tutorial/counter/state.mdx b/apps/website/docs/tutorial/counter/state.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: .state()
+description: Tutorial — define reactive state properties that trigger UI updates with the .state() builder method.
 ---
 
 import dedent from "dedent";
diff --git a/apps/website/docs/tutorial/dex/context.mdx b/apps/website/docs/tutorial/dex/context.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: context()
+description: Tutorial — share reactive state across components without prop drilling using context().
 ---
 
 import dedent from "dedent";
diff --git a/apps/website/docs/tutorial/dex/input.mdx b/apps/website/docs/tutorial/dex/input.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: .input()
+description: Tutorial — define typed external props with runtime validation using the .input() builder method.
 ---
 
 import dedent from "dedent";
diff --git a/apps/website/docs/tutorial/dex/onmount.mdx b/apps/website/docs/tutorial/dex/onmount.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: .onMount()
+description: Tutorial — run one-time setup logic after a component first renders with the .onMount() builder method.
 ---
 
 import dedent from "dedent";
diff --git a/apps/website/docs/tutorial/dex/slot.mdx b/apps/website/docs/tutorial/dex/slot.mdx
@@ -2,6 +2,7 @@
 pageType: doc-wide
 outline: false
 title: .slot()
+description: Tutorial — compose multiple components together into a parent with the .slot() builder method.
 ---
 
 import dedent from "dedent";
diff --git a/apps/website/rspress.config.ts b/apps/website/rspress.config.ts
@@ -72,6 +72,27 @@ export default defineConfig({
             defer: true,
           },
         },
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:image",
+            content: "https://ilha.build/og.jpg",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            name: "twitter:image",
+            content: "https://ilha.build/og.jpg",
+          },
+        },
+        {
+          tag: "link",
+          attrs: {
+            rel: "canonical",
+            href: "https://ilha.build",
+          },
+        },
       ],
     },
   },
