Skip to content

Commit 6a1b507

Browse files
bartlomiejuclaude
bartlomieju
and
claude
committed
docs: replace em dashes, add cross-links, update introduction and architecture
- Replace em dashes with hyphens across all changed docs - Add ~49 cross-links between doc pages for better discoverability - Restore JSX example on introduction page, remove Requirements section - Rework "Where to host" section, add AI agent mention to "When to use" - Expand scoped middleware description in architecture diagram Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 1614706 commit 6a1b507

35 files changed

Lines changed: 161 additions & 129 deletions

‎docs/latest/advanced/define.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: |
3-
Define helpers are a less TypeScripty way to declare middlewares, routes and layouts
3+
Define helpers are a less TypeScripty way to declare [middlewares](/docs/concepts/middleware), routes and [layouts](/docs/concepts/layouts)
44
---
55

66
Define helpers can be used to shorten the amount of types you have to type
@@ -72,7 +72,7 @@ export default define.page<typeof handler>((props) => {
7272
});
7373
```
7474

75-
There is also a `define.layout()` helper for layouts:
75+
There is also a `define.layout()` helper for [layouts](/docs/concepts/layouts):
7676

7777
```tsx
7878
export default define.layout((props) => {

‎docs/latest/advanced/environment-variables.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ see
99
[how to use Environment Variables in Deno](https://docs.deno.com/runtime/reference/env_variables/).
1010

1111
On top of that Fresh automatically inlines all environment variables whose names
12-
start with `FRESH_PUBLIC_` during bundling of islands.
12+
start with `FRESH_PUBLIC_` during bundling of [islands](/docs/concepts/islands).
1313

1414
> [info]: This inlining step occurs when building the app (`deno task build`).
1515
> Environment variables inside islands cannot be read at runtime.

‎docs/latest/advanced/error-handling.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,8 @@ const app = new App()
6666
```
6767

6868
Accessing an unknown route like `/invalid` will trigger the `notFound`
69-
middleware. Contrary to generic error pages this handler cannot be nested.
69+
[middleware](/docs/concepts/middleware). Contrary to generic error pages this
70+
handler cannot be nested.
7071

7172
## Throwing HTTP errors
7273

@@ -116,4 +117,4 @@ app.onError("*", (ctx) => {
116117
```
117118

118119
`HttpError` is also available in the browser via `fresh/runtime` for use in
119-
island code.
120+
[island code](/docs/concepts/islands).

‎docs/latest/advanced/head.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,13 @@ is a crucial element in HTML to set metadata for a page. It allows you to:
1212
- Include JavaScript code with `<script>`
1313

1414
> [info]: The outer HTML structure including `<head>` is typically created
15-
> inside `_app.tsx`.
15+
> inside [`_app.tsx`](/docs/concepts/app).
1616
1717
## Passing metadata from `ctx.state`
1818

19-
For simple scenarios passing metadata along from a handler or a middleware by
20-
writing to `ctx.state` is often sufficient.
19+
For simple scenarios passing metadata along from a handler or a
20+
[middleware](/docs/concepts/middleware) by writing to `ctx.state` is often
21+
sufficient.
2122

2223
```tsx routes/_app.tsx
2324
import { define } from "../util.ts";
@@ -39,8 +40,8 @@ export default define.page((ctx) => {
3940

4041
## Using the `<Head>`-component
4142

42-
For more complex scenarios, or to set page metadata from islands, Fresh ships
43-
with the `<Head>`-component.
43+
For more complex scenarios, or to set page metadata from
44+
[islands](/docs/concepts/islands), Fresh ships with the `<Head>`-component.
4445

4546
> [info]: The `<Head>` component is not dynamic by default. It will not
4647
> automatically update the document title or other head elements on the client

‎docs/latest/advanced/layouts.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ If you browse to the `/` route, Fresh will render the following HTML
3939
## Multiple layouts
4040

4141
You can register multiple layouts for different paths. Layouts are inherited
42-
from parent paths — a layout at `"*"` applies to all routes, and more specific
42+
from parent paths - a layout at `"*"` applies to all routes, and more specific
4343
layouts are added on top:
4444

4545
```ts main.ts
@@ -67,7 +67,7 @@ const app = new App()
6767

6868
## Options
6969

70-
Ignore the app wrapper component:
70+
Ignore the [app wrapper](/docs/concepts/app) component:
7171

7272
```ts main.ts
7373
app.layout("/foo/bar", MyComponent, { skipAppWrapper: true });

‎docs/latest/advanced/opentelemetry.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,17 @@ requests flow through your application.
1111

1212
Fresh creates spans for:
1313

14-
- **Middleware execution** — each middleware in the chain
15-
- **Route handler execution** — handler function calls
16-
- **Rendering** — server-side page rendering
17-
- **Static file serving** — file lookups and responses
18-
- **Lazy route loading** — dynamic imports of route modules
14+
- **[Middleware](/docs/concepts/middleware) execution** - each middleware in the
15+
chain
16+
- **Route handler execution** - handler function calls
17+
- **Rendering** - server-side page rendering
18+
- **Static file serving** - file lookups and responses
19+
- **Lazy route loading** - dynamic imports of route modules
1920

2021
## Enabling tracing
2122

2223
Fresh uses the `@opentelemetry/api` package (the vendor-neutral API). Spans are
23-
created automatically — you just need to provide an OpenTelemetry SDK and
24+
created automatically - you just need to provide an OpenTelemetry SDK and
2425
exporter to collect them.
2526

2627
If no exporter is configured, the spans are silently discarded (no performance
@@ -41,5 +42,5 @@ This exports traces to an OTLP-compatible collector (configure the endpoint with
4142

4243
### With Deno Deploy
4344

44-
[Deno Deploy](https://deno.com/deploy) collects Fresh traces automatically when
45-
using the Fresh preset — no configuration needed.
45+
[Deno Deploy](/docs/deployment/deno-deploy) collects Fresh traces automatically
46+
when using the Fresh preset - no configuration needed.

‎docs/latest/advanced/serialization.md‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@ description: |
33
What types can be passed as island props, how Fresh serializes data between server and client, and common pitfalls.
44
---
55

6-
When Fresh renders a page on the server, island props must be serialized to JSON
7-
and sent to the browser for hydration. Fresh uses a custom serialization system
8-
that supports more types than standard `JSON.stringify`.
6+
When Fresh renders a page on the server, [island](/docs/concepts/islands) props
7+
must be serialized to JSON and sent to the browser for hydration. Fresh uses a
8+
custom serialization system that supports more types than standard
9+
`JSON.stringify`.
910

1011
## Supported types
1112

@@ -25,25 +26,25 @@ The following types can be passed as island props:
2526
| `Set` | Values must be serializable |
2627
| `Map` | Keys and values must be serializable |
2728
| `Uint8Array` | Binary data |
28-
| `Signal` | From `@preact/signals` — see [Signals](/docs/concepts/signals) |
29+
| `Signal` | From `@preact/signals` - see [Signals](/docs/concepts/signals) |
2930
| `Computed Signal` | Read-only signals |
3031
| JSX Elements | Server-rendered JSX passed to islands |
3132

3233
## Not serializable
3334

3435
The following **cannot** be passed as island props:
3536

36-
- **Functions and closures** — there is no way to transfer executable code
37-
- **Class instances** — only plain objects are supported (no custom prototypes)
38-
- **Symbols** — not representable in JSON
39-
- **WeakMap / WeakSet** — cannot be enumerated
40-
- **Streams, Promises** — async values cannot be frozen for transfer
37+
- **Functions and closures** - there is no way to transfer executable code
38+
- **Class instances** - only plain objects are supported (no custom prototypes)
39+
- **Symbols** - not representable in JSON
40+
- **WeakMap / WeakSet** - cannot be enumerated
41+
- **Streams, Promises** - async values cannot be frozen for transfer
4142

4243
```tsx
43-
// WRONG — functions cannot be serialized
44+
// WRONG - functions cannot be serialized
4445
<MyIsland onClick={() => console.log("clicked")} />
4546

46-
// WRONG — class instance loses its prototype
47+
// WRONG - class instance loses its prototype
4748
<MyIsland data={new MyCustomClass()} />
4849
```
4950

@@ -70,7 +71,7 @@ When a `Signal` is detected in island props:
7071
reactive signal
7172

7273
If the same signal object is passed to multiple islands, it is serialized once
73-
and all islands receive the same signal instance on the client — keeping them
74+
and all islands receive the same signal instance on the client - keeping them
7475
synchronized.
7576

7677
Computed signals are serialized by reading their current value and wrapping it
@@ -96,5 +97,5 @@ runtime error during serialization. Keep island props to plain data:
9697
### Large props
9798

9899
Every byte of serialized props is embedded in the HTML and parsed on the client.
99-
Keep island props small — pass IDs or minimal data, and fetch the rest
100+
Keep island props small - pass IDs or minimal data, and fetch the rest
100101
client-side if needed.

‎docs/latest/advanced/troubleshooting.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ already been resolved in the latest version of Fresh.
4141

4242
Fresh 1.x heavily relied on [esm.sh](https://esm.sh/) to be able to use npm
4343
packages with Fresh. This continued a bit through the early alpha versions of
44-
Fresh 2. With the move to [`vite`](https://vite.dev/) this is not necessary
44+
Fresh 2. With the move to [`vite`](/docs/advanced/vite) this is not necessary
4545
anymore and you should use the relevant npm package directly from npm.
4646

4747
```diff deno.json

‎docs/latest/advanced/vite.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ description: |
55

66
Fresh 2 uses [Vite](https://vite.dev/) for development and production builds.
77
The Fresh Vite plugin handles JSX configuration, Hot Module Replacement (HMR),
8-
island discovery, client/server code splitting, and React-to-Preact aliasing.
8+
[island](/docs/concepts/islands) discovery, client/server code splitting, and
9+
React-to-Preact aliasing.
910

1011
## Configuration
1112

‎docs/latest/concepts/app.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ description: |
44
---
55

66
The `App` class is the heart of Fresh and routes incoming requests to the
7-
correct middlewares. This is where routes, middlewares, layouts and more are
8-
defined.
7+
correct [middlewares](/docs/concepts/middleware). This is where routes,
8+
middlewares, [layouts](/docs/concepts/layouts) and more are defined.
99

1010
```ts main.ts
1111
const app = new App()
@@ -259,8 +259,8 @@ app.all("/api/foo", async () => {
259259

260260
## `.fsRoute()`
261261

262-
Injects all file-based routes, middlewares, layouts and error pages to the app
263-
instance.
262+
Injects all [file-based routes](/docs/concepts/file-routing), middlewares,
263+
layouts and [error pages](/docs/advanced/error-handling) to the app instance.
264264

265265
```ts
266266
app.fsRoutes();
@@ -397,7 +397,7 @@ app.listen({ port: 4000 });
397397
> **Important:** `.listen()` is only used when running your app directly with
398398
> `deno run -A main.ts`. The default project setup uses `deno task dev` (Vite
399399
> dev server) and `deno task start` (`deno serve`), which spawn their own
400-
> servers — calling `.listen()` alongside these will create a second server and
400+
> servers - calling `.listen()` alongside these will create a second server and
401401
> cause `AddrInUse` errors.
402402
>
403403
> To customize the port in the default setup:

0 commit comments

Comments
 (0)