md + accept

[gfletcher-cll]

Summary

This PR adds content negotiation support (Accept: text/markdown) across the Developer Docs site, enabling all content-backed pages to be served as either HTML or Markdown from the same canonical URLs.

It also introduces a consistent pattern for direct .md endpoints and consolidates Markdown generation through a shared helper.

The result is a unified system where documentation pages can be consumed both by browsers and by tools (e.g., LLMs, scrapers, CLI workflows) without duplicating routes or content.

---

What’s included

1. Content negotiation (HTML ↔ Markdown)

All content-backed routes now:

• Inspect the Accept header
• Return Markdown when Accept: text/markdown is present
• Default to HTML otherwise

Each route also sets:

• Vary: Accept
• Link: </path.md>; rel="alternate"; type="text/markdown"

---

2. Direct .md endpoints

Added explicit .md routes for nested pages:

/<bucket>/<page>.md

Implemented via:

src/pages/<bucket>/[...id].md.ts

Special root endpoints added where needed:

• /ccip.md
• /cre-templates.md

---

3. Shared Markdown builder

All Markdown responses are generated through a single helper:

buildMarkdownDocumentFromPath(...)

This ensures:

• consistent formatting
• shared frontmatter handling
• centralized transformation logic

---

Bucket handling

Standard content buckets

Fully support negotiation + .md parity:

• vrf
• chainlink-functions
• chainlink-automation
• chainlink-local
• chainlink-nodes
• data-feeds
• data-streams
• datalink
• resources
• oracle-platform
• ace
• any-api
• architecture-overview
• getting-started
• dta-technical-standard

---

CCIP

Handled as a multi-route system:

• /ccip → root page (negotiation enabled)
• /ccip/* → main docs (negotiation enabled)
• /ccip/tutorials/* → tutorials (negotiation enabled)
• /ccip/directory/* → HTML-only (data-driven UI)

---

CRE

Handled as a hybrid route:

• /cre → root (negotiation enabled)
• /cre/<standalone> → negotiation enabled
• /cre/<page-go|page-ts> → negotiation enabled
• /cre/<page> → HTML-only redirect shell

---

CRE Templates

Special case due to content location:

• Public route: /cre-templates
• Content source: src/content/cre/templates

Handled via explicit mapping:

cre-templates → cre/templates

Supports:

• root negotiation
• nested template pages
• .md parity

---

HTML-only routes (intentionally excluded)

The following remain HTML-only because they are data-driven UI pages:

• /ccip/directory/*

These do not map to Markdown content and are out of scope for this PR.

---

Behavior examples

URL	Accept header	Result
/vrf	none	HTML
/vrf	text/markdown	Markdown
/vrf.md	any	Markdown
/cre/page	text/markdown	HTML (redirect shell)
/cre/page-ts	text/markdown	Markdown
/ccip/directory/*	any	HTML

---

Known limitations

• /ccip/directory/* routes are HTML-only (data-driven, no Markdown source)
• /cre/<canonical> routes intentionally do not return Markdown (redirect behavior)
• cre-templates uses a custom content path mapping (cre-templates → cre/templates)

---

Testing

Validated across:

• root pages
• nested pages
• CCIP main + tutorials
• CRE standalone + language routes
• CRE Templates root + nested pages

Each tested for:

• HTML response
• negotiated Markdown response
• direct .md endpoint
• parity between negotiated and direct Markdown

---

Impact

• Enables programmatic access to all documentation content
• Provides a consistent Markdown interface for LLMs and tooling
• Removes need for separate Markdown export routes
• Preserves existing HTML UX and routing behavior

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
documentation	Ready	Preview	May 1, 2026 4:30pm

[github-actions]

👋 gfletcher-cll, thanks for creating this pull request!

To help reviewers, please consider creating future PRs as drafts first. This allows you to self-review and make any final changes before notifying the team.

Once you're ready, you can mark it as "Ready for review" to request feedback. Thanks!