docs: comprehensive documentation audit, fixes, and website improvements

docs/1.x/concepts/partials.md

@@ -76,7 +76,7 @@ Let's use a typical documentation page layout as an example. It often features a
 main content area and a sidebar of links to switch between pages of the
 documentation (marked green here).
 
-![A sketched layout of a typical documentation page with the sidebar on the left composed of green links and a main content area on the right. The main content area is labeled as Partial docs-content](/docs/1.x/fresh-partial-docs.png)
+![A sketched layout of a typical documentation page with the sidebar on the left composed of green links and a main content area on the right. The main content area is labeled as Partial docs-content](/docs/fresh-partial-docs.png)
 
 The code for such a page (excluding styling) might look like this:
 

docs/check_images_test.ts

@@ -0,0 +1,55 @@
+/**
+ * Verifies that all image references in documentation markdown files
+ * point to existing files in www/static/.
+ *
+ * Run: deno test -A docs/check_images_test.ts
+ */
+import { walk } from "jsr:@std/fs@1/walk";
+import { join, resolve } from "jsr:@std/path@1";
+
+const ROOT = resolve(import.meta.dirname!);
+const PROJECT_ROOT = resolve(ROOT, "..");
+const DOCS_DIR = ROOT;
+const STATIC_DIR = join(PROJECT_ROOT, "www", "static");
+
+const IMAGE_RE = /!\[.*?\]\(([^)]+)\)/g;
+
+Deno.test("all doc image references point to existing files", async () => {
+  const errors: string[] = [];
+
+  for await (
+    const entry of walk(DOCS_DIR, {
+      exts: [".md", ".mdx"],
+      includeDirs: false,
+    })
+  ) {
+    const content = await Deno.readTextFile(entry.path);
+    const relativePath = entry.path.slice(PROJECT_ROOT.length);
+
+    for (const match of content.matchAll(IMAGE_RE)) {
+      const imgPath = match[1];
+
+      // Skip external URLs
+      if (imgPath.startsWith("http://") || imgPath.startsWith("https://")) {
+        continue;
+      }
+
+      // Doc image paths like "/docs/foo.png" map to "www/static/docs/foo.png"
+      const fsPath = join(STATIC_DIR, imgPath);
+
+      try {
+        await Deno.stat(fsPath);
+      } catch {
+        errors.push(`${relativePath}: image not found: ${imgPath}`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(
+      `Found ${errors.length} broken image reference(s):\n\n${
+        errors.join("\n")
+      }`,
+    );
+  }
+});

docs/latest/advanced/api-reference.md

@@ -0,0 +1,95 @@
+---
+description: |
+  Quick reference for all public exports from Fresh's entry points: fresh, fresh/runtime, and fresh/dev.
+---
+
+This page lists all public exports from Fresh's entry points.
+
+## `fresh`
+
+The main entry point for server-side code.
+
+```ts
+import { App, createDefine, HttpError, page, staticFiles } from "fresh";
+```
+
+| Export            | Kind     | Description                                                                                        |
+| ----------------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `App`             | Class    | The main application class. See [App](/docs/concepts/app).                                         |
+| `staticFiles`     | Function | Middleware for serving static files. See [Static Files](/docs/concepts/static-files).              |
+| `createDefine`    | Function | Create type-safe `define.*` helpers. See [Define Helpers](/docs/advanced/define).                  |
+| `page`            | Function | Return data from a handler to a page component. See [Data Fetching](/docs/concepts/data-fetching). |
+| `HttpError`       | Class    | Throw HTTP errors with status codes. See [Error Handling](/docs/advanced/error-handling).          |
+| `cors`            | Function | CORS middleware. See [cors](/docs/plugins/cors).                                                   |
+| `csrf`            | Function | CSRF protection middleware. See [csrf](/docs/plugins/csrf).                                        |
+| `csp`             | Function | Content Security Policy middleware. See [csp](/docs/plugins/csp).                                  |
+| `trailingSlashes` | Function | Trailing slash enforcement middleware. See [trailingSlashes](/docs/plugins/trailing-slashes).      |
+
+**Types:**
+
+| Export                                | Description                                                                          |
+| ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `Context` / `FreshContext`            | The request context passed to all middlewares and handlers.                          |
+| `PageProps`                           | Props received by page components (includes `data`, `url`, `params`, `state`, etc.). |
+| `Middleware` / `MiddlewareFn`         | Middleware function type.                                                            |
+| `HandlerFn`                           | Single handler function type.                                                        |
+| `HandlerByMethod`                     | Object with per-method handler functions.                                            |
+| `RouteHandler`                        | Union of `HandlerFn` and `HandlerByMethod`.                                          |
+| `PageResponse`                        | Return type of `page()`.                                                             |
+| `RouteConfig`                         | Route configuration (`routeOverride`, `skipInheritedLayouts`, etc.).                 |
+| `LayoutConfig`                        | Layout configuration (`skipInheritedLayouts`, `skipAppWrapper`).                     |
+| `Define`                              | Type of the object returned by `createDefine()`.                                     |
+| `FreshConfig` / `ResolvedFreshConfig` | App configuration types.                                                             |
+| `ListenOptions`                       | Options for `app.listen()`.                                                          |
+| `Island`                              | Island component type.                                                               |
+| `Method`                              | HTTP method union type.                                                              |
+| `RouteData`                           | Data type returned by route handlers via `page()`.                                   |
+| `Lazy` / `MaybeLazy`                  | Utility types for lazily-loaded routes and middleware.                               |
+| `CORSOptions`                         | Options for `cors()`.                                                                |
+| `CsrfOptions`                         | Options for `csrf()`.                                                                |
+| `CSPOptions`                          | Options for `csp()`.                                                                 |
+
+## `fresh/runtime`
+
+Shared runtime utilities for both server and client code. Safe to import in
+islands.
+
+```ts
+import {
+  asset,
+  assetSrcSet,
+  Head,
+  HttpError,
+  IS_BROWSER,
+  Partial,
+} from "fresh/runtime";
+```
+
+| Export        | Kind      | Description                                                                                    |
+| ------------- | --------- | ---------------------------------------------------------------------------------------------- |
+| `IS_BROWSER`  | Constant  | `true` in the browser, `false` on the server. Use to guard browser-only code.                  |
+| `asset`       | Function  | Add cache-busting query params to asset URLs. See [Static Files](/docs/concepts/static-files). |
+| `assetSrcSet` | Function  | Apply `asset()` to all URLs in a `srcset` string.                                              |
+| `Partial`     | Component | Mark a region for partial updates. See [Partials](/docs/advanced/partials).                    |
+| `Head`        | Component | Add elements to the document `<head>`. See [Modifying head](/docs/advanced/head).              |
+| `HttpError`   | Class     | HTTP error class (re-exported from `fresh`).                                                   |
+
+## `fresh/dev`
+
+Development and build tools. Only used in `dev.ts` (legacy) or build scripts.
+
+```ts
+import { Builder } from "fresh/dev";
+```
+
+| Export    | Kind  | Description                                                            |
+| --------- | ----- | ---------------------------------------------------------------------- |
+| `Builder` | Class | Pre-Vite build system (legacy). See [Builder](/docs/advanced/builder). |
+
+**Types:**
+
+| Export                                                   | Description                   |
+| -------------------------------------------------------- | ----------------------------- |
+| `BuildOptions`                                           | Options for `new Builder()`.  |
+| `ResolvedBuildConfig`                                    | Resolved build configuration. |
+| `OnTransformArgs` / `OnTransformOptions` / `TransformFn` | Build plugin hook types.      |

docs/latest/advanced/builder.md

@@ -171,7 +171,7 @@ For more information on how to use tailwindcss, check out
 You can customize the tailwind plugin via the following options:
 
 ```ts dev.ts
-tailwind(builder, app, {
+tailwind(builder, {
   // Exclude certain files from processing
   exclude: ["/admin/**", "*.temp.css"],
   // Force optimization (defaults to production mode)
@@ -183,7 +183,7 @@ tailwind(builder, app, {
 
 ### Tailwindcss v3
 
-If can't update to the current version of tailwindcss we have a dedicated
+If you can't update to the current version of tailwindcss we have a dedicated
 `@fresh/plugin-tailwindcss-v3` plugin that uses tailwindcss v3. That way you can
 decided on your own when it's best to update to v4.
 

docs/latest/advanced/define.md

@@ -5,7 +5,7 @@ description: |
 
 Define helpers can be used to shorten the amount of types you have to type
 yourself in code. They are entirely optional as some developers prefer the
-explicitness of types, other's like the convenience of `define.*` helpers.
+explicitness of types, others like the convenience of `define.*` helpers.
 
 Without define helpers:
 

docs/latest/advanced/environment-variables.md

@@ -1,6 +1,6 @@
 ---
 description: |
-  Error pages can be used to customize the page that is shown when an error occurs in the application.
+  How to use environment variables in Fresh, including public variables that are inlined into island bundles.
 ---
 
 Environment variables in Deno are typically read via `Deno.env.get()` or

docs/latest/advanced/error-handling.md

@@ -71,7 +71,13 @@ middleware. Contrary to generic error pages this handler cannot be nested.
 ## Throwing HTTP errors
 
 If you need to bail out of execution and need to respond with a particular HTTP
-error code, you can use Fresh's `HttpError` class.
+error code, you can use Fresh's `HttpError` class:
+
+```ts
+import { HttpError } from "fresh";
+```
+
+`HttpError` takes a status code and an optional message:
 
 ```ts middleware/auth.ts
 import { HttpError } from "fresh";
@@ -84,11 +90,17 @@ async function authMiddleware(ctx) {
     throw new HttpError(404);
   }
 
+  // Forbidden with a custom message
+  if (!isAdmin(user)) {
+    throw new HttpError(403, "Admin access required");
+  }
+
   return await ctx.next();
 }
 ```
 
-You can check the status code of the thrown `HttpError` in your error handler:
+When an `HttpError` is thrown, Fresh catches it and invokes the error handler.
+You can check the status code in your error handler:
 
 ```ts main.ts
 app.onError((ctx) => {
@@ -100,3 +112,6 @@ app.onError((ctx) => {
   // ...
 });
 ```
+
+`HttpError` is also available in the browser via `fresh/runtime` for use in
+island code.

docs/latest/advanced/head.md

@@ -77,5 +77,10 @@ the matching element:
 5. No matching element was found, Fresh will create a new one and append it to
    `<head>`
 
+When multiple `<Head>` components render an element with the same key, the
+**last one rendered wins**. Since Fresh renders top-down (app wrapper → layout →
+route → page component), a route page can override defaults set in `_app.tsx` by
+using the same `key` prop.
+
 > [info]: The `<title>`-tag is automatically deduplicated, even without a `key`
 > prop.

docs/latest/advanced/index.md

@@ -4,3 +4,24 @@ description: |
 ---
 
 This section of the documentation describes advanced functionality of Fresh.
+
+- [App wrapper](/docs/advanced/app-wrapper) - Customize the outer HTML structure
+- [Layouts](/docs/advanced/layouts) - Define programmatic layouts
+- [Error handling](/docs/advanced/error-handling) - Custom error and 404 pages
+- [Partials](/docs/advanced/partials) - Client-side partial page updates
+- [Forms](/docs/advanced/forms) - Handle form submissions
+- [Define helpers](/docs/advanced/define) - Type-safe route and middleware
+  helpers
+- [Serialization](/docs/advanced/serialization) - What types can be passed as
+  island props
+- [Environment variables](/docs/advanced/environment-variables) - Use env vars
+  in islands
+- [Modifying <head>](/docs/advanced/head) - Manage meta tags, titles, and
+  styles
+- [Vite plugin options](/docs/advanced/vite) - Configure the Fresh Vite plugin
+- [OpenTelemetry](/docs/advanced/opentelemetry) - Built-in tracing and
+  observability
+- [API Reference](/docs/advanced/api-reference) - All public exports from Fresh
+- [Troubleshooting](/docs/advanced/troubleshooting) - Common issues and
+  solutions
+- [Builder (Legacy)](/docs/advanced/builder) - Pre-Vite build system

docs/latest/advanced/layouts.md

@@ -2,6 +2,10 @@
 description: "Create re-usable layouts across routes"
 ---
 
+This page covers **programmatic layouts** defined via `app.layout()`. If you're
+using file-based routing, see [Layouts (file-based)](/docs/concepts/layouts)
+instead.
+
 Layouts are plain Preact components that are inherited based on the matching
 pattern. When you have a section on your site where all pages share the same
 HTML structure and only the content changes, a layout is a neat way to abstract
@@ -32,14 +36,37 @@ If you browse to the `/` route, Fresh will render the following HTML
 </div>
 ```
 
-## Options
+## Multiple layouts
+
+You can register multiple layouts for different paths. Layouts are inherited
+from parent paths — a layout at `"*"` applies to all routes, and more specific
+layouts are added on top:
+
+```ts main.ts
+const app = new App()
+  .layout("*", MainLayout) // Applied to all routes
+  .layout("/admin/*", AdminLayout) // Added on top for /admin/* routes
+  .get("/", (ctx) => ctx.render(<h1>Home</h1>))
+  .get("/admin/dashboard", (ctx) => ctx.render(<h1>Dashboard</h1>));
+```
+
+For `/admin/dashboard`, both `MainLayout` and `AdminLayout` will wrap the page
+component (MainLayout as the outer wrapper, AdminLayout as the inner).
+
+## Overriding layouts
 
-Add a layout and ignore all previously inherited ones.
+Use `skipInheritedLayouts` to replace all inherited layouts with a single one:
 
 ```ts main.ts
-app.layout("/foo/bar", MyComponent, { skipInheritedLayouts: true });
+const app = new App()
+  .layout("*", MainLayout)
+  .layout("/landing", LandingLayout, { skipInheritedLayouts: true })
+  .get("/", (ctx) => ctx.render(<h1>Home</h1>)) // Uses MainLayout
+  .get("/landing", (ctx) => ctx.render(<h1>Landing</h1>)); // Uses only LandingLayout
 ```
 
+## Options
+
 Ignore the app wrapper component:
 
 ```ts main.ts

docs/latest/advanced/opentelemetry.md

@@ -0,0 +1,45 @@
+---
+description: |
+  Fresh has built-in OpenTelemetry instrumentation for tracing requests through middleware, handlers, and rendering.
+---
+
+Fresh automatically instruments key operations with
+[OpenTelemetry](https://opentelemetry.io/) spans, giving you visibility into how
+requests flow through your application.
+
+## What's instrumented
+
+Fresh creates spans for:
+
+- **Middleware execution** — each middleware in the chain
+- **Route handler execution** — handler function calls
+- **Rendering** — server-side page rendering
+- **Static file serving** — file lookups and responses
+- **Lazy route loading** — dynamic imports of route modules
+
+## Enabling tracing
+
+Fresh uses the `@opentelemetry/api` package (the vendor-neutral API). Spans are
+created automatically — you just need to provide an OpenTelemetry SDK and
+exporter to collect them.
+
+If no exporter is configured, the spans are silently discarded (no performance
+overhead).
+
+### With Deno's built-in OpenTelemetry
+
+Deno has
+[built-in OpenTelemetry support](https://docs.deno.com/runtime/fundamentals/open_telemetry/).
+Enable it with the `OTEL_DENO` environment variable:
+
+```sh Terminal
+OTEL_DENO=true deno task start
+```
+
+This exports traces to an OTLP-compatible collector (configure the endpoint with
+`OTEL_EXPORTER_OTLP_ENDPOINT`).
+
+### With Deno Deploy
+
+[Deno Deploy](https://deno.com/deploy) collects Fresh traces automatically when
+using the Fresh preset — no configuration needed.