Dualmark

https://dualmark.dev/docs
Admin
Dualmark is an AI-optimized documentation framework that creates markdown twins for web pages to...
Tokens:23,065
Snippets:260
Trust Score:2.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install @dualmark/cloudflare and @dualmark/core

Source: https://dualmark.dev/docs/integrations/cloudflare-workers

Install the necessary packages using your preferred package manager.

```bash
bun add @dualmark/cloudflare @dualmark/core
```

```bash
npm install @dualmark/cloudflare @dualmark/core
```

```bash
yarn add @dualmark/cloudflare @dualmark/core
```

--------------------------------

### Install and run @dualmark/cli with npm

Source: https://dualmark.dev/docs/packages/cli

Installs the CLI globally using npm and demonstrates how to run it ad-hoc.

```bash
npm install -g @dualmark/cli
# or run ad-hoc:
bunx @dualmark/cli verify https://example.com
```

--------------------------------

### Install Dualmark for Next.js (bun)

Source: https://dualmark.dev/docs/quickstart

Install the necessary Dualmark packages for Next.js using bun.

```bash
bun add @dualmark/nextjs @dualmark/core @dualmark/converters
```

--------------------------------

### Install and run @dualmark/cli with Yarn

Source: https://dualmark.dev/docs/packages/cli

Installs the CLI globally using Yarn and demonstrates how to run it ad-hoc.

```bash
yarn global add @dualmark/cli
# or run ad-hoc:
yarn dlx @dualmark/cli verify https://example.com
```

--------------------------------

### Install and run @dualmark/cli with Bun

Source: https://dualmark.dev/docs/packages/cli

Installs the CLI globally using Bun and demonstrates how to run it ad-hoc to verify a URL.

```bash
bun add -g @dualmark/cli
# or run ad-hoc:
bunx @dualmark/cli verify https://example.com
```

--------------------------------

### Install Dualmark for Next.js (npm)

Source: https://dualmark.dev/docs/quickstart

Install the necessary Dualmark packages for Next.js using npm.

```bash
npm install @dualmark/nextjs @dualmark/core @dualmark/converters
```

--------------------------------

### Run Development Server and Verify

Source: https://dualmark.dev/docs/quickstart

Start the development server and then verify your deployment from a new terminal.

```bash
bunx wrangler dev
# new terminal:
bunx @dualmark/cli verify http://localhost:8787/your-page
```

--------------------------------

### Install Dualmark for Astro (bun)

Source: https://dualmark.dev/docs/quickstart

Install the necessary Dualmark packages for Astro using bun.

```bash
bun add @dualmark/astro @dualmark/core @dualmark/converters
```

--------------------------------

### Install Dualmark for Next.js (yarn)

Source: https://dualmark.dev/docs/quickstart

Install the necessary Dualmark packages for Next.js using yarn.

```bash
yarn add @dualmark/nextjs @dualmark/core @dualmark/converters
```

--------------------------------

### Install Dualmark for Astro (npm)

Source: https://dualmark.dev/docs/quickstart

Install the necessary Dualmark packages for Astro using npm.

```bash
npm install @dualmark/astro @dualmark/core @dualmark/converters
```

--------------------------------

### Install @dualmark/core with Bun

Source: https://dualmark.dev/docs/packages/core

Use this command to add the @dualmark/core package to your project when using Bun.

```bash
bun add @dualmark/core
```

--------------------------------

### Install Dualmark Packages

Source: https://dualmark.dev/docs/integrations/nextjs

Install the necessary Dualmark packages for your Next.js project using bun, npm, or yarn.

```bash
bun add @dualmark/nextjs @dualmark/core @dualmark/converters
```

```bash
npm install @dualmark/nextjs @dualmark/core @dualmark/converters
```

```bash
yarn add @dualmark/nextjs @dualmark/core @dualmark/converters
```

--------------------------------

### Install @dualmark/cloudflare and @dualmark/core with Bun

Source: https://dualmark.dev/docs/packages/cloudflare

Use this command to add the necessary packages to your project when using Bun as your package manager.

```bash
bun add @dualmark/cloudflare @dualmark/core
```

--------------------------------

### Install @dualmark/converters

Source: https://dualmark.dev/docs/packages/converters

Install the converters package and core package using your preferred package manager.

```bash
bun add @dualmark/converters @dualmark/core
```

```bash
npm install @dualmark/converters @dualmark/core
```

```bash
yarn add @dualmark/converters @dualmark/core
```

--------------------------------

### Install Dualmark for Astro (yarn)

Source: https://dualmark.dev/docs/quickstart

Install the necessary Dualmark packages for Astro using yarn.

```bash
yarn add @dualmark/astro @dualmark/core @dualmark/converters
```

--------------------------------

### Install @dualmark/cloudflare and @dualmark/core with npm

Source: https://dualmark.dev/docs/packages/cloudflare

Use this command to add the necessary packages to your project when using npm as your package manager.

```bash
npm install @dualmark/cloudflare @dualmark/core
```

--------------------------------

### Install Dualmark Packages

Source: https://dualmark.dev/docs/integrations/astro

Install the necessary Dualmark packages for Astro using your preferred package manager.

```bash
bun add @dualmark/astro @dualmark/core @dualmark/converters
```

```bash
npm install @dualmark/astro @dualmark/core @dualmark/converters
```

```bash
yarn add @dualmark/astro @dualmark/core @dualmark/converters
```

--------------------------------

### Install @dualmark/core with npm

Source: https://dualmark.dev/docs/packages/core

Use this command to add the @dualmark/core package to your project when using npm.

```bash
npm install @dualmark/core
```

--------------------------------

### Path conversion examples

Source: https://dualmark.dev/docs/packages/core

Demonstrates the usage of toMarkdownPath and toMarkdownUrl for converting file paths and URLs to their markdown equivalents.

```typescript
toMarkdownPath("/blog/post");           // -> "/blog/post.md"
toMarkdownPath("/");                    // -> "/index.md"
toMarkdownPath("/blog/post.md");        // -> "/blog/post.md"  (idempotent)

toMarkdownUrl("https://x.com/blog?q=1"); // -> "https://x.com/blog.md?q=1"
```

--------------------------------

### Install @dualmark/core with Yarn

Source: https://dualmark.dev/docs/packages/core

Use this command to add the @dualmark/core package to your project when using Yarn.

```bash
yarn add @dualmark/core
```

--------------------------------

### Collection Configuration Example

Source: https://dualmark.dev/docs/packages/astro

Configure collections to define content types, slug strategies, and listing metadata.

```typescript
collections: {
  blog: {
    converter: "blog" | "case-study" | "changelog" | "compare" | "docs"
              | "feature" | "glossary" | "integration" | "legal" | "pricing" | "pseo"
              | "tool" | "video"
              | ((entry) => string),  // or custom function

    slugStrategy?: "single" | "nested",  // single = /blog/<slug>, nested = /blog/<...>

    listingMetadata?: {
      title?: string;
      description?: string;
    },
  },
}
```

--------------------------------

### Install @dualmark/cloudflare and @dualmark/core with Yarn

Source: https://dualmark.dev/docs/packages/cloudflare

Use this command to add the necessary packages to your project when using Yarn as your package manager.

```bash
yarn add @dualmark/cloudflare @dualmark/core
```

--------------------------------

### Browser Request Example

Source: https://dualmark.dev/docs/spec/content-negotiation

Demonstrates a typical browser request with an Accept header that includes multiple media types and quality values. The server should respond with HTML.

```http
GET /blog/hello HTTP/1.1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
```

--------------------------------

### Blog Converter Example

Source: https://dualmark.dev/docs/packages/converters

Demonstrates how to use the blogConverter factory to create a markdown converter function and apply it to a collection entry.

```typescript
import { blogConverter } from "@dualmark/converters";

const convert = blogConverter({
  siteUrl: "https://example.com",
  basePath: "/blog",
  categoryBasePath: "/blog/category",
  brandFooter: "## About\n\nWe build widgets.",
});

const md = convert({
  id: "first-post",
  data: {
    title: "Hello",
    description: "First post",
    publishedDate: new Date("2026-05-05"),
    author: "Alice",
    category: "announcements",
  },
  body: "Long-form content.",
});
```

--------------------------------

### Verify Cloudflare Worker Setup

Source: https://dualmark.dev/docs/integrations/cloudflare-workers

Run the local development server and use the @dualmark/cli to verify the worker's functionality. This is crucial for ensuring all features are working as expected.

```bash
wrangler dev
# new terminal:
bunx @dualmark/cli verify http://localhost:8787/blog/your-post
```

--------------------------------

### Base llms.txt Format Example

Source: https://dualmark.dev/docs/spec/llms-txt-extensions

Illustrates the fundamental structure of an llms.txt file, including brand name, description, and sections with page links.

```markdown
# Brand Name

> One-paragraph description suitable for AI summarization.

## Section Title

Optional section description.

- [Page Title](https://example.com/page): Optional description
- [Another Page](https://example.com/other)

## Another Section

- [Item](https://example.com/item)
```

--------------------------------

### createLlmsTxtHandler(options)

Source: https://dualmark.dev/docs/packages/nextjs

Generates `{ GET }` for the `app/llms.txt/route.ts` file, providing structured information for LLMs about your site's content and structure.

```APIDOC
## `createLlmsTxtHandler(options)`

Returns `{ GET }` for `app/llms.txt/route.ts`.

### Parameters

- **options** (object) - Configuration options for the `llms.txt` handler.
  - **brandName** (string) - The name of the brand.
  - **description** (string) - A description of the site or content.
  - **sections** (LlmsTxtSection[]) - An array of sections to include in the `llms.txt` file.
    - **title** (string) - The title of the section.
    - **links** (object[]) - An array of links within the section.
      - **title** (string) - The title of the link.
      - **href** (string) - The URL of the link.

### Request Example

```ts
// app/llms.txt/route.ts
import { createLlmsTxtHandler } from "@dualmark/nextjs";

const handler = createLlmsTxtHandler({
  brandName: "Acme",
  description: "Acme's docs and blog.",
  sections: [
    {
      title: "Pages",
      links: [
        { title: "Home", href: "https://example.com/" },
        { title: "Blog", href: "https://example.com/blog" },
      ],
    },
  ],
});

export const dynamic = "force-static";
export const GET = handler.GET;
```
```

--------------------------------

### Tied Preference Example

Source: https://dualmark.dev/docs/spec/content-negotiation

Demonstrates a request with equally weighted preferences for HTML and markdown. The reference implementation prefers HTML, but other implementations may choose markdown.

```http
GET /blog/hello HTTP/1.1
Accept: text/html;q=0.5, text/markdown;q=0.5
```

--------------------------------

### Verify Dualmark Setup in Next.js

Source: https://dualmark.dev/docs/integrations/nextjs

Run this command in your terminal to verify your Dualmark integration with a running Next.js development server. Ensure the Next.js dev server is running in one terminal before executing the verification command in another.

```bash
bun run dev
# new terminal:
bunx @dualmark/cli verify http://localhost:3000/posts/your-post
```

--------------------------------

### Markdown Sitemap Example

Source: https://dualmark.dev/docs/spec/discovery.md

An optional markdown file at /sitemap.md listing all markdown twins, useful for AI agents preferring markdown discovery.

```markdown
# Sitemap

## Blog
- [Hello World](/blog/hello.md)
- [Second Post](/blog/second.md)

## Pages
- [Home](/index.md)
- [About](/about.md)
```

--------------------------------

### AI Agent Request Example

Source: https://dualmark.dev/docs/spec/content-negotiation

Illustrates a request from an AI agent, which may trigger markdown content delivery. The server should respond with markdown, respecting the User-Agent.

```http
GET /blog/hello HTTP/1.1
User-Agent: Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)
Accept: */*
```

--------------------------------

### Generate a markdown response

Source: https://dualmark.dev/docs/packages/core

Example of creating an HTTP Response object with markdown content and custom options like caching and redirects.

```typescript
markdownResponse("# Hello", {
  cacheControl: "public, max-age=3600",
  noindex: true,
  redirectFrom: "/old",
  redirectTo: "/new",
  extraHeaders: { "X-Custom": "value" },
});
```

--------------------------------

### Permissive robots.txt for AI Agents

Source: https://dualmark.dev/docs/spec/discovery.md

A conformant server should allow AI agents to crawl the site unless explicitly blocked. This example shows permissive directives.

```robots.txt
User-agent: GPTBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: PerplexityBot
Allow: /

# ... etc
```

--------------------------------

### Explicit Markdown Request Example

Source: https://dualmark.dev/docs/spec/content-negotiation

Shows a request where the client explicitly asks for markdown content using the Accept header. The server should respond with markdown.

```http
GET /blog/hello HTTP/1.1
Accept: text/markdown
```

--------------------------------

### Render LLMs text content

Source: https://dualmark.dev/docs/packages/core

Example of using renderLlmsTxt to generate structured text content for LLMs, including brand name, description, and links.

```typescript
const body = renderLlmsTxt({
  brandName: "Acme",
  description: "Acme's docs.",
  sections: [
    { title: "Pages", links: [{ title: "Home", href: "/" }] },
  ],
});
```

--------------------------------

### Minimal Dualmark Handler

Source: https://dualmark.dev/docs/integrations/manual

This is a basic example of a request handler that uses @dualmark/core to negotiate content format, detect AI bots, and return either markdown or HTML responses.

```typescript
import { negotiateFormat, detectAIBot, markdownResponse } from "@dualmark/core";

export async function handle(request: Request): Promise<Response> {
  const accept = request.headers.get("accept") ?? "";
  const ua = request.headers.get("user-agent") ?? "";
  const bot = detectAIBot(ua);
  const fmt = negotiateFormat(accept);

  if (fmt === null && accept) {
    return new Response("Not Acceptable", { status: 406, headers: { Vary: "Accept" } });
  }

  if (bot.isBot || fmt === "markdown") {
    return markdownResponse("# Hello\n\nThis is the markdown twin.", {
      cacheControl: "public, max-age=3600",
    });
  }

  const html = "<html><body>Hello</body></html>";
  const md = "/hello.md";
  return new Response(html, {
    headers: {
      "Content-Type": "text/html; charset=utf-8",
      Link: `<${md}>; rel="alternate"; type="text/markdown"`,
      Vary: "Accept",
    },
  });
}
```

--------------------------------

### AEO Recommended 'What We Do Not Do' Section

Source: https://dualmark.dev/docs/spec/llms-txt-extensions

Provides an example of the 'What We Do Not Do' section, which helps disambiguate brands and prevent AI confusion. This section is recommended by AEO.

```markdown
## What We Do Not Do

- Acme Corp does not sell physical products
- Acme Corp is not affiliated with Acme Industries (defunct)
- Acme Corp does not provide consulting services
```

--------------------------------

### Create a Cloudflare Worker with createAEOWorker

Source: https://dualmark.dev/docs/packages/cloudflare

This example demonstrates how to create a Cloudflare Worker using the `createAEOWorker` function, configuring upstream workers, redirects, skips, analytics, headers, and hooks.

```typescript
import { createAEOWorker } from "@dualmark/cloudflare";

export default createAEOWorker({
  upstream: existingWorker,
  trailingSlash: "never",
  enableLinkHeader: true,

  redirects: {
    internal: { "/old": "/new" },
    external: { "/login": "https://app.example.com" },
  },

  skip: {
    prefixes: ["/admin", "/api/"],
    extensions: [".js", ".css", ".png"],
  },

  analytics: { binding: "AI_AGENT_ANALYTICS" },

  headers: { cacheControl: "public, max-age=3600" },

  hooks: {
    onAIRequest: (info) => console.log(info.botName, info.pathname),
    onMiss: (info) => console.warn("miss:", info.pathname),
  },
});
```

--------------------------------

### CLI Usage and Options

Source: https://dualmark.dev/docs/packages/cli

Shows the basic command structure for `dualmark verify` and lists available options for customizing the test run.

```bash
dualmark verify <url> [options]

Options:
  --json                Output a machine-readable JSON report
  --skip-negotiation    Skip negotiation checks (use for static-only sites)
  --timeout <ms>        Per-request timeout (default: 10000)
  --help, -h            Show help
```

--------------------------------

### Build and Verify Astro Site

Source: https://dualmark.dev/docs/quickstart

Build the Astro site and verify Dualmark integration using the CLI.

```bash
bun run build
bun run dev
# in another terminal:
bunx @dualmark/cli verify http://localhost:4321/blog/your-post
```

--------------------------------

### Verify Dualmark Integration

Source: https://dualmark.dev/docs/integrations/astro

Run the development server and use the Dualmark CLI to verify your integration by checking a specific blog post URL.

```bash
bun run dev
# new terminal:
bunx @dualmark/cli verify http://localhost:4321/blog/your-post
```

--------------------------------

### Verify Deployment with CLI

Source: https://dualmark.dev/docs/quickstart

Use the Dualmark CLI to verify your deployed application at the specified URL.

```bash
bunx @dualmark/cli verify http://localhost:3000/your-page
```

--------------------------------

### Run Dualmark Conformance Test

Source: https://dualmark.dev/docs/spec/conformance

Use the `@dualmark/cli` tool to verify a website's conformance against the Dualmark specification.

```bash
dualmark verify https://example.com/blog/hello
```

--------------------------------

### Programmatic llms.txt Generation with @dualmark/core

Source: https://dualmark.dev/docs/spec/llms-txt-extensions

Demonstrates how to use the renderLlmsTxt function from @dualmark/core to programmatically generate a conformant llms.txt file from a structured configuration object.

```typescript
import { renderLlmsTxt } from "@dualmark/core";

const txt = renderLlmsTxt({
  brandName: "Acme",
  description: "Widgets for everyone.",
  sections: [
    {
      title: "Core Products",
      links: [
        { title: "Widget", href: "https://acme.test/widget", description: "Our widget" },
      ],
    },
    {
      title: "What We Do Not Do",
      links: [],
      description: "- Acme does not sell physical products.",
    },
  ],
});
```

--------------------------------

### 406 Not Acceptable Case Example

Source: https://dualmark.dev/docs/spec/content-negotiation

Represents a scenario where the client's Accept header does not match any supported media types. The server should respond with a 406 status code.

```http
GET /blog/hello HTTP/1.1
Accept: image/png
```

--------------------------------

### Minimal Astro Configuration

Source: https://dualmark.dev/docs/integrations/astro

Configure Dualmark with essential options for basic site functionality, including collection mapping and LLM text generation.

```javascript
import { defineConfig } from "astro/config";
import dualmark from "@dualmark/astro";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    dualmark({
      siteUrl: "https://example.com",
      collections: { 
        blog: { converter: "blog" }, 
      },
      llmsTxt: { enabled: true }, 
    }),
  ],
});
```

--------------------------------

### createDualmarkMiddleware(options)

Source: https://dualmark.dev/docs/packages/nextjs

Creates a Next.js proxy/middleware function that rewrites markdown URLs, detects AI bots, and handles content negotiation. It should be paired with a static `config.matcher`.

```APIDOC
## `createDualmarkMiddleware(options)`

Returns the Next.js proxy/middleware function. Pair it with a static `config.matcher` literal.

### Parameters

- **options** (object) - Configuration options for the middleware.
  - **siteUrl** (string) - The base URL of the website.
  - **internalNamespace** (string, optional) - The internal namespace for handling markdown files. Defaults to "md".
  - **middleware** (object, optional) - Middleware specific options.
    - **injectLinkHeader** (boolean, optional) - Whether to inject the Link header. Defaults to true.
    - **skipPaths** (string[], optional) - Additional path prefixes the middleware ignores.
  - **headers** (object, optional) - HTTP headers configuration.
    - **cacheControl** (string, optional) - The Cache-Control header value. Defaults to "public, max-age=3600".
    - **noindex** (boolean, optional) - Whether to set the noindex header. Defaults to true.

### Usage

```ts
// proxy.ts
import { createDualmarkMiddleware } from "@dualmark/nextjs";

export default createDualmarkMiddleware({
  siteUrl: "https://example.com",
});

export const config = {
  matcher: [
    {
      source: "/((?!_next/|favicon.ico|md/).*)",
      missing: [{ type: "header", key: "next-router-prefetch" }],
    },
  ],
};
```

_On Next.js ≤15, name the file `middleware.ts` instead. Body is identical._

The middleware:

- Rewrites `*.md` URLs to the internal `/md/<path>` namespace
- Detects 24 known AI bot User-Agents and rewrites their requests to markdown
- Honors `Accept: text/markdown` per RFC 7231
- Returns `406 Not Acceptable` when the request explicitly excludes both `text/html` and `text/markdown`
- Adds `Link: <...>; rel="alternate"; type="text/markdown"` and `Vary: Accept` to HTML responses

<Callout>
  The matcher must be an inline literal -- Next.js statically parses `export const config` and rejects imports/expressions. If you customize `internalNamespace`, replace `md/` accordingly.
</Callout>
```

--------------------------------

### createDualmarkRouteHandler(options)

Source: https://dualmark.dev/docs/packages/nextjs

Generates `{ GET, generateStaticParams }` for a catch-all route handler in the App Router. This allows dynamic rendering of collections, static pages, and parameterized routes.

```APIDOC
## `createDualmarkRouteHandler(options)`

Returns `{ GET, generateStaticParams }` for the catch-all `app/<namespace>/[...path]/route.ts`.

### Parameters

- **options** (object) - Configuration options for the route handler.
  - **siteUrl** (string) - The base URL of the website.
  - **collections** (Record<string, CollectionConfig>, optional) - Configuration for collections of content.
    - **converter** (string) - The name of the converter to use for this collection.
    - **getEntries** (function) - A function that returns an array of entries for the collection.
    - **listingMetadata** (object, optional) - Metadata for the collection listing.
      - **title** (string) - The title of the listing.
      - **description** (string, optional) - The description of the listing.
  - **staticPages** (StaticPageConfig[], optional) - Configuration for static pages.
    - **pattern** (string) - The URL pattern for the static page.
    - **render** (function) - A function that returns the content of the static page.
  - **parameterizedRoutes** (ParameterizedRouteConfig[], optional) - Configuration for parameterized routes.
    - **pattern** (string) - The URL pattern for the parameterized route.
    - **getStaticPaths** (function) - A function that returns an array of possible parameter values.
    - **render** (function) - A function that renders the content for a given set of parameters.
  - **internalNamespace** (string, optional) - The internal namespace for handling markdown files. Defaults to "md".
  - **llmsTxt** (object, optional) - Configuration for the `llms.txt` handler.
    - **enabled** (boolean, optional) - Whether to enable the `llms.txt` handler.
    - **brandName** (string, optional) - The brand name to use in `llms.txt`.
    - **description** (string, optional) - The description to use in `llms.txt`.
    - **sections** (LlmsTxtSection[], optional) - Sections to include in `llms.txt`.
  - **middleware** (object, optional) - Middleware specific options.
    - **injectLinkHeader** (boolean, optional) - Whether to inject the Link header. Defaults to true.
    - **skipPaths** (string[], optional) - Additional path prefixes the middleware ignores.
  - **headers** (object, optional) - HTTP headers configuration.
    - **cacheControl** (string, optional) - The Cache-Control header value. Defaults to "public, max-age=3600".
    - **noindex** (boolean, optional) - Whether to set the noindex header. Defaults to true.

### Request Example

```ts
// app/md/[...path]/route.ts
import { createDualmarkRouteHandler } from "@dualmark/nextjs";
import { POSTS } from "@/lib/posts";

const handler = createDualmarkRouteHandler({
  siteUrl: "https://example.com",
  collections: {
    posts: {
      converter: "blog",
      getEntries: () => POSTS.map(toEntry),
      listingMetadata: { title: "Posts", description: "All posts." },
    },
  },
  staticPages: [
    { pattern: "/", render: () => "# Home\n\nWelcome." },
    { pattern: "/about", render: () => "# About" },
  ],
  parameterizedRoutes: [
    {
      pattern: "/tax/[country]",
      getStaticPaths: () => [
        { params: { country: "us" } },
        { params: { country: "uk" } },
      ],
      render: ({ params }) => `# Tax: ${params.country.toUpperCase()}`,
    },
  ],
});

export const dynamic = "force-static";
export const GET = handler.GET;
export const generateStaticParams = handler.generateStaticParams;
```
```

--------------------------------

### Configure Dualmark in Astro

Source: https://dualmark.dev/docs/quickstart

Add Dualmark integration to your Astro configuration file.

```javascript
import { defineConfig } from "astro/config";
import dualmark from "@dualmark/astro";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    dualmark({
      siteUrl: "https://example.com",
      collections: {
        blog: { converter: "blog" },
      },
      llmsTxt: { enabled: true },
    }),
  ],
});
```

--------------------------------

### withDualmark(nextConfig, options)

Source: https://dualmark.dev/docs/packages/nextjs

Wraps your Next.js configuration to add Dualmark workspace packages to `transpilePackages` and validate options. This is the primary way to integrate Dualmark into your Next.js application's build process.

```APIDOC
## `withDualmark(nextConfig, options)`

Wrap your Next.js config. Adds the dualmark workspace packages to `transpilePackages` and validates the options at boot.

### Parameters

- **nextConfig** (object) - The existing Next.js configuration object.
- **options** (object) - Configuration options for Dualmark.
  - **siteUrl** (string) - The base URL of the website.
  - **internalNamespace** (string, optional) - The internal namespace for handling markdown files. Defaults to "md".
  - **collections** (Record<string, CollectionConfig>, optional) - Configuration for collections of content.
  - **staticPages** (StaticPageConfig[], optional) - Configuration for static pages.
  - **parameterizedRoutes** (ParameterizedRouteConfig[], optional) - Configuration for parameterized routes.
  - **llmsTxt** (object, optional) - Configuration for the `llms.txt` handler.
    - **enabled** (boolean, optional) - Whether to enable the `llms.txt` handler.
    - **brandName** (string, optional) - The brand name to use in `llms.txt`.
    - **description** (string, optional) - The description to use in `llms.txt`.
    - **sections** (LlmsTxtSection[], optional) - Sections to include in `llms.txt`.
  - **middleware** (object, optional) - Middleware specific options.
    - **injectLinkHeader** (boolean, optional) - Whether to inject the Link header. Defaults to true.
    - **skipPaths** (string[], optional) - Additional path prefixes the middleware ignores.
  - **headers** (object, optional) - HTTP headers configuration.
    - **cacheControl** (string, optional) - The Cache-Control header value. Defaults to "public, max-age=3600".
    - **noindex** (boolean, optional) - Whether to set the noindex header. Defaults to true.

### Request Example

```ts
// next.config.mjs
import { withDualmark } from "@dualmark/nextjs";

export default withDualmark(
  { reactStrictMode: true },
  { siteUrl: "https://example.com" },
);
```
```

--------------------------------

### Create Next.js Route Handler with createDualmarkRouteHandler

Source: https://dualmark.dev/docs/packages/nextjs

Set up a catch-all route handler for Next.js App Router using `createDualmarkRouteHandler`. This provides `GET` and `generateStaticParams` exports.

```typescript
import { createDualmarkRouteHandler } from "@dualmark/nextjs";
import { POSTS } from "@/lib/posts";

const handler = createDualmarkRouteHandler({
  siteUrl: "https://example.com",
  collections: {
    posts: {
      converter: "blog",
      getEntries: () => POSTS.map(toEntry),
      listingMetadata: { title: "Posts", description: "All posts." },
    },
  },
  staticPages: [
    { pattern: "/", render: () => "# Home\n\nWelcome." },
    { pattern: "/about", render: () => "# About" },
  ],
  parameterizedRoutes: [
    {
      pattern: "/tax/[country]",
      getStaticPaths: () => [
        { params: { country: "us" } },
        { params: { country: "uk" } },
      ],
      render: ({ params }) => `# Tax: ${params.country.toUpperCase()}`,
    },
  ],
});

export const dynamic = "force-static";
export const GET = handler.GET;
export const generateStaticParams = handler.generateStaticParams;
```

--------------------------------

### Dualmark Layered Architecture

Source: https://dualmark.dev/docs/concepts

Illustrates the three core layers of Dualmark: the public Spec, the Framework implementation, and the Conformance CLI for verification.

```text
┌─────────────────────────────────────────┐
│ Spec (AEO Spec v1.0)                    │
│   The public contract                   │
│                                         │
│   ↓ implemented by                      │
│                                         │
│ Framework (@dualmark/core + adapters)   │
│   The reference implementation          │
│                                         │
│   ↓ verified by                         │
│                                         │
│ Conformance (@dualmark/cli)             │
│   The score                             │
└─────────────────────────────────────────┘
```

--------------------------------

### dualmark verify <url> [options]

Source: https://dualmark.dev/docs/packages/cli

Runs conformance tests against a given URL. Supports JSON output, skipping negotiation, and custom timeouts.

```APIDOC
## dualmark verify <url> [options]

### Description
Runs conformance tests against a given URL. Supports JSON output, skipping negotiation, and custom timeouts.

### Method
CLI Command

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to verify.

#### Query Parameters
- **--json** (boolean) - Optional - Output a machine-readable JSON report.
- **--skip-negotiation** (boolean) - Optional - Skip negotiation checks (use for static-only sites).
- **--timeout** (number) - Optional - Per-request timeout in milliseconds (default: 10000).
- **--help, -h** (boolean) - Optional - Show help.
```

--------------------------------

### Configure next.config.mjs with Dualmark

Source: https://dualmark.dev/docs/integrations/nextjs

Use the `withDualmark` higher-order function to integrate Dualmark into your Next.js configuration file.

```javascript
import { withDualmark } from "@dualmark/nextjs";

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};

export default withDualmark(nextConfig, {
  siteUrl: "https://example.com",
});
```

--------------------------------

### Create Parameterized Routes in Next.js

Source: https://dualmark.dev/docs/packages/nextjs

Set up dynamic routes with patterns, static path generation, and render functions that accept route parameters. Generates dynamic Markdown files.

```typescript
parameterizedRoutes: [
  {
    pattern: "/tax/[country]",
    getStaticPaths: async () => [
      { params: { country: "us" } },
      { params: { country: "uk" } },
    ],
    render: ({ params }) => `# Tax in ${params.country.toUpperCase()}`,
  },
]
```

--------------------------------

### Configure Astro Integration

Source: https://dualmark.dev/docs/packages/astro

Add the dualmark integration to your Astro project's configuration file.

```typescript
import { defineConfig } from "astro/config";
import dualmark from "@dualmark/astro";

export default defineConfig({
  integrations: [dualmark({ /* config */ })],
});
```

--------------------------------

### Parameterized Routes Configuration

Source: https://dualmark.dev/docs/packages/astro

Set up parameterized routes with dynamic paths, static path generation, and rendering logic.

```typescript
parameterizedRoutes: [
  {
    pattern: "/tax/[country]\n",
    getStaticPaths: async () => [
      { params: { country: "us" } },
      { params: { country: "uk" } },
    ],
    render: ({ country }) => `# Tax in ${country.toUpperCase()}\n\n...`,
  },
],
```

--------------------------------

### Add Dualmark Proxy and Route Handler for Next.js

Source: https://dualmark.dev/docs/quickstart

Set up the middleware for proxying requests and a route handler for Dualmark content.

```typescript
import { createDualmarkMiddleware } from "@dualmark/nextjs";

export default createDualmarkMiddleware({ siteUrl: "https://example.com" });

export const config = {
  matcher: [
    {
      source: "/((?!_next/|favicon.ico|md/).*)",
      missing: [{ type: "header", key: "next-router-prefetch" }],
    },
  ],
};

```

```typescript
import { createDualmarkRouteHandler } from "@dualmark/nextjs";
import { POSTS } from "@/lib/posts";

const handler = createDualmarkRouteHandler({
  siteUrl: "https://example.com",
  collections: {
    posts: {
      converter: "blog",
      getEntries: () => POSTS.map((p) => ({ id: p.slug, data: p, body: p.body })),
    },
  },
});

export const dynamic = "force-static";
export const GET = handler.GET;
export const generateStaticParams = handler.generateStaticParams;

```

--------------------------------

### Verify a URL using the CLI

Source: https://dualmark.dev/docs/conformance/cli

Run the verify command with a URL to check its conformance to the AEO Spec.

```bash
bunx @dualmark/cli verify https://example.com/blog/your-post
```

--------------------------------

### Configure Next.js with withDualmark

Source: https://dualmark.dev/docs/packages/nextjs

Wrap your Next.js configuration object with `withDualmark` to enable dualmark features. This adds dualmark packages to `transpilePackages` and validates options.

```typescript
import { withDualmark } from "@dualmark/nextjs";

export default withDualmark(
  { reactStrictMode: true },
  { siteUrl: "https://example.com" },
);
```

--------------------------------

### Minimum llms.txt Structure

Source: https://dualmark.dev/docs/spec/discovery.md

A recommended file at the root path describing the site's AI-relevant content. It should include brand information and a list of pages.

```markdown
# Brand Name

> Short description.

## Section Name

- [Page Title](https://example.com/page): Optional description
```

--------------------------------

### negotiateFormat

Source: https://dualmark.dev/docs/packages/core

Picks the best response format. Returns `null` when neither HTML nor markdown is acceptable.

```APIDOC
## negotiateFormat(accept: string): "html" | "markdown" | null

### Description
Picks the best response format based on the `Accept` header. Returns `null` when neither HTML nor markdown is acceptable, indicating the caller should respond with `406 Not Acceptable`.

### Parameters
#### Query Parameters
- **accept** (string) - Required - The Accept header string to negotiate format from.
```

--------------------------------

### Full Astro Configuration with Dualmark

Source: https://dualmark.dev/docs/integrations/astro

A comprehensive Dualmark configuration for Astro, including advanced collection settings, static page rendering, parameterized routes, LLM text customization, and middleware options.

```javascript
dualmark({
  siteUrl: "https://example.com",

  collections: {
    blog: {
      converter: "blog",
      slugStrategy: "single",
      listingMetadata: {
        title: "Blog",
        description: "All blog posts.",
      },
    },
    glossary: { converter: "glossary" },
    docs: {
      converter: (entry) => `# ${entry.data.title}\n\n${entry.body}`,
    },
  },

  staticPages: [
    { pattern: "/", render: () => "# Home\n\nWelcome." },
    { pattern: "/about", render: () => "# About" },
  ],

  parameterizedRoutes: [
    {
      pattern: "/tax/[country]",
      getStaticPaths: async () => [{ params: { country: "us" } }, { params: { country: "uk" } }],
      render: ({ country }) => `# Tax: ${country.toUpperCase()}\n\n...`,
    },
  ],

  llmsTxt: {
    enabled: true,
    brandName: "Acme",
    description: "Acme's docs and blog.",
    sections: [
      {
        title: "Pages",
        links: [
          { title: "Home", href: "https://example.com/" },
          { title: "Blog", href: "https://example.com/blog" },
        ],
      },
    ],
  },

  middleware: { injectLinkHeader: true },

  cacheControl: "public, max-age=3600",
  noindex: true,
});
```

--------------------------------

### Import content negotiation utilities

Source: https://dualmark.dev/docs/packages/core

Import the necessary functions for parsing Accept headers and negotiating response formats.

```typescript
import { parseAcceptHeader, negotiateFormat } from "@dualmark/core";
```

--------------------------------

### Import markdown response utilities

Source: https://dualmark.dev/docs/packages/core

Import functions for generating HTTP responses with markdown content and alternate links.

```typescript
import { markdownResponse, injectMarkdownAlternateLink } from "@dualmark/core";
```

--------------------------------

### Base Converter Configuration

Source: https://dualmark.dev/docs/packages/converters

Illustrates the common configuration options available for all converter factories, including siteUrl and brandFooter.

```typescript
interface BaseConverterConfig {
  siteUrl: string;        // required, used for absolute URLs
  brandFooter?: string;   // appended to every output
}
```

--------------------------------

### Import composition helper functions

Source: https://dualmark.dev/docs/packages/core

Import functions for generating common markdown patterns like listings, related links, and FAQs.

```typescript
import { listingToMarkdown, renderRelatedLinks, renderFAQSection } from "@dualmark/core";
```

--------------------------------

### Import AI bot detection utilities

Source: https://dualmark.dev/docs/packages/core

Import the AI_BOTS registry and the detectAIBot function for identifying AI crawlers.

```typescript
import { AI_BOTS, detectAIBot } from "@dualmark/core";
```

--------------------------------

### Configure Dualmark in Next.js

Source: https://dualmark.dev/docs/quickstart

Wrap your Next.js config with the Dualmark higher-order component.

```javascript
import { withDualmark } from "@dualmark/nextjs";

/** @type {import('next').NextConfig} */
const nextConfig = { reactStrictMode: true };

export default withDualmark(nextConfig, {
  siteUrl: "https://example.com",
});
```

--------------------------------

### Programmatic API for URL Verification

Source: https://dualmark.dev/docs/packages/cli

Demonstrates how to use the `verifyUrl` function programmatically to test a URL and format the results as a text report. It also shows how to check for failed required checks to exit with a non-zero status code.

```typescript
import { verifyUrl, formatTextReport } from "@dualmark/cli";

const result = await verifyUrl("https://example.com/blog/post", {
  skipNegotiation: false,
  timeoutMs: 10_000,
});

console.log(formatTextReport(result));

if (result.failed.some((c) => c.required)) {
  process.exit(1);
}
```

--------------------------------

### Create Dualmark Middleware in proxy.ts

Source: https://dualmark.dev/docs/integrations/nextjs

Set up the Dualmark middleware to handle routing and content negotiation for your Next.js application. Ensure the `matcher` configuration uses an inline literal.

```typescript
import { createDualmarkMiddleware } from "@dualmark/nextjs";

export default createDualmarkMiddleware({
  siteUrl: "https://example.com",
});

export const config = {
  matcher: [
    {
      source: "/((?!_next/|favicon.ico|md/).*)",
      missing: [{ type: "header", key: "next-router-prefetch" }],
    },
  ],
};
```

--------------------------------

### Static Site Worker Configuration

Source: https://dualmark.dev/docs/integrations/cloudflare-workers

Configure a worker to serve static assets from env.ASSETS with AI bot detection and other features. Ensure 'run_worker_first: true' in wrangler.jsonc.

```typescript
import { createAEOWorker } from "@dualmark/cloudflare";

const upstream = {
  async fetch(request: Request, env, _ctx) {
    return env.ASSETS.fetch(request);
  },
};

export default createAEOWorker({
  upstream,
  trailingSlash: "never",
  enableLinkHeader: true,
  analytics: { binding: "AI_AGENT_ANALYTICS" },
});
```

```jsonc
{
  "name": "my-site",
  "main": "./worker.ts",
  "compatibility_date": "2026-05-04",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
    "run_worker_first": true
  },
  "analytics_engine_datasets": [
    {
      "binding": "AI_AGENT_ANALYTICS",
      "dataset": "ai_events"
    }
  ]
}
```

--------------------------------

### llms.txt Configuration

Source: https://dualmark.dev/docs/packages/astro

Enable and configure the generation of an llms.txt file from provided sections.

```typescript
llmsTxt: {
  enabled: true,
  brandName: "Acme",
  description: "Acme's docs and blog.",
  sections: [
    {
      title: "Pages",
      links: [
        { title: "Home", href: "https://example.com/" },
        { title: "Blog", href: "https://example.com/blog" },
      ],
    },
  ],
}
```

--------------------------------

### Create LLM Text Handler for llms.txt

Source: https://dualmark.dev/docs/integrations/nextjs

Use `createLlmsTxtHandler` to generate a route handler for the `/llms.txt` endpoint, providing brand information and links for LLM consumption.

```typescript
import { createLlmsTxtHandler } from "@dualmark/nextjs";

const handler = createLlmsTxtHandler({
  brandName: "Acme",
  description: "Acme's docs and blog.",
  sections: [
    {
      title: "Pages",
      links: [
        { title: "Home", href: "https://example.com/" },
        { title: "Posts", href: "https://example.com/posts" },
      ],
    },
  ],
});

export const dynamic = "force-static";
export const GET = handler.GET;
```

--------------------------------

### DualmarkAstroConfig Interface

Source: https://dualmark.dev/docs/packages/astro

Defines the configuration options for the Dualmark Astro integration.

```typescript
interface DualmarkAstroConfig {
  siteUrl: string;

  collections?: Record<string, CollectionConfig>;

  staticPages?: StaticPageConfig[];

  parameterizedRoutes?: ParameterizedRouteConfig[];

  llmsTxt?: {
    enabled?: boolean;
    brandName?: string;
    description?: string;
    sections?: LlmsTxtSection[];
  };

  middleware?: { injectLinkHeader?: boolean };

  cacheControl?: string;
  noindex?: boolean;
}
```

--------------------------------

### renderFAQSection

Source: https://dualmark.dev/docs/packages/core

Renders a Frequently Asked Questions (FAQ) section in markdown format.

```APIDOC
## renderFAQSection(section: object): string

### Description
Generates a markdown formatted section for Frequently Asked Questions (FAQ). This helper function structures questions and answers in a clear, readable format.

### Parameters
#### Request Body
- **section** (object) - Required - The data structure representing the FAQ section, likely containing questions and answers.
```

--------------------------------

### Import Dualmark Next.js API

Source: https://dualmark.dev/docs/packages/nextjs

Import necessary functions and types from the '@dualmark/nextjs' package for middleware, route handlers, configuration resolution, and utility functions.

```typescript
import {
  createDualmarkMiddleware,
  createDualmarkRouteHandler,
  createLlmsTxtHandler,
  withDualmark,
  resolveConfig,
  resolveBuiltInConverter,
  buildMatcherSource,
  toInternalMarkdownPath,
  DUALMARK_DEFAULT_MATCHER_SOURCE,
  DualmarkConfigError,
  type DualmarkNextConfig,
  type CollectionConfig,
  type StaticPageConfig,
  type ParameterizedRouteConfig,
} from "@dualmark/nextjs";
```

--------------------------------

### Programmatic API Imports

Source: https://dualmark.dev/docs/packages/astro

Import necessary functions from the @dualmark/astro package for programmatic use.

```typescript
import {
  createDualmarkIntegration,
  resolveConfig,
  resolveBuiltInConverter,
  DualmarkConfigError,
} from "@dualmark/astro";
```

--------------------------------

### Import text utility functions

Source: https://dualmark.dev/docs/packages/core

Import various text manipulation functions for markdown conversion.

```typescript
import { normalizeUnicode, cleanBody, slugToTitle, fmtDate, joinLines } from "@dualmark/core";
```
Tokens:
Raw