Agents

Rebask is designed to work with agents, from the documentation to the APIs. We provide the tooling your agents need to understand and use Rebask, so you don't have to.

Author's note: Docs are hard because they hold up a mirror to the tool. They ask: is Rebask really as good and simple as I imagine? I take them seriously because the docs are where that promise is tested.
I want Rebask to work like a hammer. A good hammer disappears in your hand: you do not think about it, or read a manual before every swing. You focus on the nail. The docs exist to make the hammer worthy of that focus.

Cheatsheet

The Rebask cheatsheet is the fastest entry point. It covers setup, routing, rendering, caching, deployment, and the runtime APIs. Read it first, then follow its links for the details.

Agents should use the Markdown cheatsheet . That is the version intended for them.

Documentation as Markdown

Every documentation page is available as Markdown. Request the .md URL, or send Accept: text/markdown:

curl https://www.rebask.com/docs/routing/introduction.md
curl -H "Accept: text/markdown" https://www.rebask.com/docs/routing/introduction

The llms.txt index links every documentation page and points agents at the cheatsheet first.

`AGENTS.md`

Add this block to the AGENTS.md in a Rebask project:

## Rebask

Read https://www.rebask.com/cheatsheet.md before changing Rebask routing, rendering, caching, or
deployment code. Follow its links for details. Request docs as Markdown with
`Accept: text/markdown` or a `.md` URL.

Skill

Install the Rebask skill for coding agents:

npx skills add lfades/vext --skill rebask

The skill is a short pointer to the cheatsheet and the docs conventions. The cheatsheet remains the source of truth.

Verify changes

Run vite build. It fails for invalid route configuration and for a dynamic page that cannot produce a shell.

At runtime, x-rebask-cache and x-rebask-prerender show cache and PPR behavior. See DevTools for the headers and the Rebask panels.

Markdown

Add a markdown.md file next to a page for static Markdown, or a markdown.ts file when the Markdown needs to be generated at request time:

app/
  page.tsx
  markdown.md
  docs/[[...slug]]/
    page.tsx
    markdown.ts

A directory cannot define both markdown.md and markdown.ts. A Markdown file can live next to a page.tsx but not route.ts.

`markdown.md`

# Docs

This page is also available as Markdown.

The file content is served as text/markdown without parsing or rendering. It can be the only file for a route, making the route Markdown-only. HTML and RSC requests to a Markdown-only route go through the normal 404 response.

`markdown.ts`

// app/docs/[[...slug]]/markdown.ts
import { routeParams } from "@rebask/core/request"

export default async function markdown() {
  const { slug } = await routeParams<{ slug?: string[] }>()
  const doc = await getDoc((slug ?? []).join("/"))

  if (!doc) return new Response("# Not found\n", { status: 404 })

  return doc.source
}

The default export receives no arguments. Use request APIs such as routeParams(), headers(), cookies(), and searchParam() when needed. Return a string or a Response:

A string is served as text/markdown; charset=utf-8.
A Response can set a custom status, headers, or a stream.

Return a Response with status 404 when there is no Markdown for the request, or custom 404 markdown content.

Reading request APIs such as headers() makes the handler dynamic, so its result is not cached.

Markdown cache lifetimes

Markdown pages are static by default just like normal pages are. Use cacheLife to change their lifetime:

import { cacheLife } from "@rebask/core/cache"

export default function markdown() {
	cacheLife({ revalidate: 300, expire: 3600 })
	return "# Docs\n"
}

A Markdown handler that reads request APIs is not cached, regardless of cacheLife. An explicit Cache-Control response header can also set the lifetime.

Negotiation

Rebask serves the Markdown representation when a request includes text/markdown in Accept with a positive quality value that does not rank below text/html. Requests that do not list Markdown fall back to HTML, including requests with no Accept header.

Markdown responses set Vary: Accept and a canonical Link header. HTML responses for routes with a Markdown file include an alternate Link to the .md URL. If a page has no Markdown representation, a request that lists Markdown receives the HTML page.

Markdown URLs

A page at /docs/start also has a Markdown URL at /docs/start.md. The root page uses /.md. Set markdownUrls: false to disable these URLs:

rebask({ markdownUrls: false })

Routes still answer Accept: text/markdown even with markdownUrls disabled.

Not found markdown pages

If Markdown is requested for a URL that matches no page, Rebask uses the Markdown file of the matching catch-all page marked notFound when one exists. The response has status 404, cache-control: no-store, and x-robots-tag: noindex. Without one, Rebask returns a minimal Markdown 404.

Prerendering markdown

During a build, Rebask prerenders Markdown for static paths and stores it in the cache. Markdown that reads the request, such as through cookies() or headers(), stays dynamic.

For a Markdown-only route with dynamic params, you can export prerenderParams from markdown.ts:

export function prerenderParams() {
  return { params: [{ slug: "start" }], allowExtraParams: false }
}

export default function markdown() {
  return "# Start"
}

When a route has both page.tsx and markdown.ts, prerenderParams belongs in page.tsx. Exporting it from both is an error.

PreviousIntroduction Next Routing