feat(layer): add Vercel markdown-rewrite module

[amondnet]

Summary

Adds packages/layer/modules/markdown-rewrite.ts — a build-time Nuxt module that injects rewrite rules into Vercel's build-output config.json so AI agents get raw markdown instead of the SPA shell.

Ports docus upstream commits:

• 6fd8686b — feat(llms): redirect homepage to /llms.txt
• 9ceafe6f — feat(llms): add docs page redirection to raw markdown for agents

See docs/docus-upstream-changes.md item #9.

Behaviour

• No-op on every non-Vercel preset. The check is preset.startsWith('vercel'), so it covers vercel, vercel-edge, vercel-static, etc.
• On Vercel: read <output.publicDir>/../config.json (the Vercel build-output config), confirm llms.txt was emitted, then unshift route pairs onto routes so they fire before the SPA fallback.
• Rules emitted when the request carries Accept: text/markdown or User-Agent: curl/*:
  • ^/$ → /llms.txt
  • ^/<locale>/?$ → /llms.txt (one per runtimeConfig.public.i18n.locales entry)
  • ^<page>$ → /raw<page>.md (one per /raw/...md link discovered in llms.txt)
• Vercel's has array is AND-ed, so OR semantics between the Accept and User-Agent matchers require emitting two rule entries per src → dest pair.
• Locale codes are regex-escaped before being joined into the alternation, so an exotic code can't break the pattern.

Conventions

• Module style follows the existing packages/layer/modules/{config,shadcn}.ts (defineNuxtModule + named module).
• TypeScript only; an inline VercelBuildOutputConfig / VercelRoute / VercelHeaderHas interface describes the parts we touch — no any.
• Module is registered in packages/layer/nuxt.config.ts immediately after ./modules/shadcn.

Verification

bun install
cd packages/layer && bun typecheck      # no errors in markdown-rewrite.ts
cd ../.. && bun lint                     # clean

# Vercel build
NITRO_PRESET=vercel bun --filter @pleaseai/docs-site build
jq '.routes[] | select(.has // empty)' apps/docs/.vercel/output/config.json

Output (homepage rules only, because the current nuxt-llms config emits links to canonical /docs/... URLs rather than /raw/...md — the per-page rules will start being emitted as soon as llms.txt carries raw-md links):

{
  "src": "^/$",
  "dest": "/llms.txt",
  "headers": { "content-type": "text/markdown; charset=utf-8" },
  "has": [{ "type": "header", "key": "accept", "value": "(.*)text/markdown(.*)" }],
  "continue": true
}
{
  "src": "^/$",
  "dest": "/llms.txt",
  "headers": { "content-type": "text/markdown; charset=utf-8" },
  "has": [{ "type": "header", "key": "user-agent", "value": "curl/.*" }],
  "continue": true
}

Default (cloudflare) build is unaffected — the module bails silently and dist/ is produced as before.

Notes

• Per-page rules require llms.txt to enumerate /raw/...md URLs. The current site config doesn't, so only the homepage routes are emitted today. This matches the upstream behaviour and avoids accidentally rewriting asset URLs. Wiring nuxt-llms to also emit raw-md URLs is tracked separately.
• Runtime e2e is Vercel-only (build-output rewrites apply at the edge), so verification here is limited to inspecting the generated config.json.

Follow-up to #27.

[gemini-code-assist]

Code Review

This pull request introduces a new Nuxt module, markdown-rewrite.ts, which automatically injects Vercel rewrite routes to serve raw markdown files (such as llms.txt and raw documentation pages) to AI agents requesting markdown content via specific headers or user agents. The feedback suggests improving the robustness of these routes by decoding URL-encoded characters in the paths using decodeURIComponent and allowing optional trailing slashes in the regex patterns for docs pages.

[cubic-dev-ai]

2 issues found across 2 files

Architecture diagram

sequenceDiagram
    participant Nuxt as Nuxt Build Process
    participant MDModule as markdown-rewrite Module
    participant FS as File System
    participant Vercel as Vercel Build Output Config

    Note over Nuxt,Vercel: Build-time Module Flow (Vercel Preset Only)

    Nuxt->>MDModule: nitro:init hook
    MDModule->>MDModule: Check preset startsWith('vercel')
    alt Non-Vercel preset
        MDModule-->>Nuxt: No-op (return early)
    else Vercel preset
        MDModule->>FS: Read <publicDir>/../config.json
        alt Read fails
            FS-->>MDModule: Error
            MDModule->>MDModule: log.warn (skip rewrites)
        else Parse fails
            MDModule->>MDModule: log.warn (skip rewrites)
        else Success
            FS-->>MDModule: raw JSON
            MDModule->>FS: Read <publicDir>/llms.txt
            alt llms.txt missing
                FS-->>MDModule: Error
                MDModule->>MDModule: log.warn (skip rewrites)
            else llms.txt found
                FS-->>MDModule: llms.txt content
                MDModule->>MDModule: Build route definitions
                Note over MDModule: For each src→dest pair,<br/>create 2 routes (Accept AND curl)
                MDModule->>MDModule: Rule 1: ^/$ → /llms.txt
                MDModule->>MDModule: Rule 2: ^/(locale)/?$ → /llms.txt (per locale)
                MDModule->>MDModule: Rule 3: ^<page>$ → /raw<page>.md (from llms.txt links)
                MDModule->>MDModule: Escape regex in locale codes & page paths
                MDModule->>Vercel: unshift routes into vcConfig.routes
                alt Success
                    Vercel-->>MDModule: Updated config
                    MDModule->>FS: Write config.json
                    FS-->>MDModule: Done
                    MDModule->>MDModule: log.info (injected N routes)
                end
            end
        end
    end
    MDModule-->>Nuxt: Module setup complete

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cloudflare-workers-and-pages]

Deploying docs-please with    Cloudflare Pages

Latest commit:	c2d844b
Status:	⚡️  Build in progress...

View logs

[sonarqubecloud]

Quality Gate failed

Failed conditions
1 Security Hotspot

See analysis details on SonarQube Cloud