Skip to content

feat(site): ready for agents: Markdown by content negotiation, JSON-LD, trust pages - #102

Merged
b4rb13 merged 3 commits into
mainfrom
site/agent-ready
Nov 20, 2026
Merged

b4rb13 merged 3 commits into
mainfrom
site/agent-ready

Conversation

@b4rb13

@b4rb13 b4rb13 commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

Summary

Changes from an Is Agentic scan (56/100), for the items that apply to a documentation site.

request ── Accept prefers text/markdown? ──no──▶ static page (as before) + Vary: Accept
                    │yes  (apps/site/middleware.ts, Vercel Routing Middleware)
                    ├─ /x/.md exists ─▶ 200 text/markdown, Vary: Accept
                    ├─ HTML-only page ─▶ 200 Markdown summary (title, description, links on)
                    └─ nothing ───────▶ 404 text/markdown: "Page not found" + llms.txt, llms-full, sitemap
+apps/site/middleware.ts                           content negotiation, in one file (static files and /_vercel never run it)
+apps/site/vercel.json                             Vary: Accept on pages
 src/pages/[...slug].md.ts                         every page gets a .md copy (was: docs only)
+src/markdown/home.md                              /index.md written for agents
 src/pages/llms.txt.ts                             + "When to use Dotquilt", "How an agent should use it", about/contact/privacy
+src/routeData.ts                                  og:image everywhere; home: og:type website + JSON-LD SoftwareApplication
+public/og.png                                     1200×630 social card (the home page's first screen)
+public/robots.txt                                 allows every crawler (as before) and names the sitemap; it was a 404
+content/docs/{about,contact,privacy}.mdx          trust pages, linked from the footer
Scan item Here
1 Agent-friendly 404s Done: a 404 with a Markdown body when Markdown is asked for
4 Markdown negotiation Done: home and every page, with Vary: Accept
7 JSON-LD Done: SoftwareApplication with version, license, offers, sameAs
9 When to use Done, in llms.txt
13 Trust pages Done: About, Contact, Privacy (each over 500 characters)
14 Metadata Done: og:image added; canonical, lang and og:type were already there
2, 3, 10, 11 OpenAPI, JSON errors, API schema, function calling Not applicable: Dotquilt is a client-side library with no HTTP API. A spec would be invented.
8 CLI Not applicable for now: there's no CLI to publish (a product decision)
12 Organization address and contactPoint Needs the owner: a postal address and contact email
5, 6 Search discoverability Helped by JSON-LD keywords and the og card; ranking takes indexing time

Evidence

  • scripts/site-markdown.test.ts (11 tests):

    • The middleware compiles alone and loads in Node, as Vercel runs it. The first preview failed every request with MIDDLEWARE_INVOCATION_FAILED: Vercel doesn't bundle middleware.ts, so its import of a helpers file couldn't be found (ERR_MODULE_NOT_FOUND). This test fails on that version and passes now that the helpers live in middleware.ts.
    • Accept parsing: Markdown-first gets Markdown; browsers, */* and HTML-first don't.
    • The path mapping.
    • The middleware with fetch stubbed: pass-through for browsers; 200 text/markdown + Vary: Accept for a page; a summary for an HTML-only page; a Markdown 404; HEAD without a body.
  • tests/site/discovery.spec.ts:

    • JSON-LD (it carries the core package's version), og:image and og:type, canonical and lang;
    • the trust pages have real content and are linked from the footer;
    • /index.md, the new llms.txt sections, and robots.txt (fails on the old build, where it was a 404).
  • Site tests: 82 passed. Unit tests: 38 passed. bun run lint and bun run check pass.

  • On this PR's preview (befc6b7):

    Request Answer
    / with Accept: text/markdown 200 text/markdown, Vary: Accept, # Dotquilt
    / as a browser asks (text/html,…,*/*;q=0.8) 200 text/html, Vary: Accept
    HEAD / with text/markdown 200 text/markdown, no body
    /docs/installation/, /docs/components/skeleton/, /about/, /privacy/ with text/markdown 200 text/markdown, the page
    /license/, /playground/ with text/markdown 200 text/markdown, a summary
    /__probe-404 with text/markdown 404 text/markdown, # Page not found
    /__probe-404 with text/html 404 HTML page, as before
    /index.md, /llms.txt, /llms-full.txt, /setup-prompt.md, /sitemap-index.xml, /robots.txt, /og.png 200 with the right type
    Home page in a browser renders and animates as before; JSON-LD SoftwareApplication v0.1.1

Merge Danger

Door: two-way

Blast Radius: every page's response path

The middleware runs before every page request. It returns early unless the request prefers text/markdown, and it never runs for files (/_astro, images, .md, .txt). Removing middleware.ts turns it off.

🤖 Generated with Claude Code

…D, trust pages

From an Is Agentic scan (56/100). For the items that apply to a docs site:

- Markdown content negotiation and agent-friendly 404s: apps/site/
  middleware.ts (Vercel Routing Middleware) answers requests that prefer
  text/markdown with the page's Markdown copy, a short summary for
  interactive pages, or a 404 with a Markdown body that links llms.txt and
  the sitemap; Content-Type text/markdown and Vary: Accept. Browsers get
  the static pages as before; vercel.json adds Vary: Accept to them.
- Every page now has a Markdown copy, including /index.md (written for
  agents: what Dotquilt is, install, quick start, components, links) and
  the interactive pages, which say where to open them.
- llms.txt says when to use Dotquilt (and when not), and how an agent
  should add it.
- JSON-LD SoftwareApplication on the home page (version read from the
  core package), og:type website, and an og:image social card (1200x630,
  the home page's first screen) on every page, through Starlight route
  middleware.
- /about/, /contact/ and /privacy/ pages, linked from the footer. The
  privacy page states what the site collects: Vercel hosting and cookieless
  Web Analytics, Google Fonts, the theme choice in local storage.

Tests: scripts/site-markdown.test.ts covers the negotiation and the
middleware (fetch stubbed); tests/site/discovery.spec.ts covers JSON-LD,
the social card, the trust pages, /index.md and llms.txt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
dotquilt Ready Ready Preview Nov 20, 2026 9:00pm UTC

Request Review

b4rb13 and others added 2 commits November 21, 2026 00:57
Vercel compiles middleware.ts on its own without bundling and runs it in
Node, so the import of src/lib/negotiation could not be resolved and every
request on the preview failed with MIDDLEWARE_INVOCATION_FAILED. The
helpers now live in middleware.ts, and a test compiles it alone and loads
it in Node, as Vercel does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dotquilt.dev answered /robots.txt with a 404. It now allows every crawler,
as before, and points crawlers and agents to sitemap-index.xml.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@b4rb13
b4rb13 merged commit 3059432 into main Nov 20, 2026
9 checks passed
@b4rb13
b4rb13 deleted the site/agent-ready branch November 20, 2026 21:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant