feat: markdown frontmatter metadata for .md routes

[Kinfe123]

Summary by cubic

Add YAML frontmatter to all machine-readable docs markdown routes to improve agent parsing and citations. Each response now includes title, optional description, canonical_url, markdown_url, and last_updated when known.

• New Features
  • Prepends frontmatter unless the document already has one.
  • Normalizes last_updated from page lastmod/lastModified to YYYY-MM-DD.
  • Builds absolute URLs using configured LLMs base URL or the request origin.
  • Applied across the shared docs API and adapters (Astro, SvelteKit, Nuxt, TanStack Start); not-found markdown responses include the same metadata.
  • Updated tests and docs to reflect the new frontmatter.

^{Written for commit 72b1e0c. Summary will update on new commits. Review in cubic}

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	May 27, 2026 12:20pm

[pkg-pr-new]

Open in StackBlitz

@farming-labs/astro

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/astro@223

@farming-labs/astro-theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/astro-theme@223

@farming-labs/docs

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/docs@223

@farming-labs/theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/theme@223

@farming-labs/next

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/next@223

@farming-labs/nuxt

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/nuxt@223

@farming-labs/nuxt-theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/nuxt-theme@223

@farming-labs/svelte

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/svelte@223

@farming-labs/svelte-theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/svelte-theme@223

@farming-labs/tanstack-start

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/tanstack-start@223

commit: 72b1e0c

[cubic-dev-ai]

2 issues found across 13 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/docs/src/agent.ts">

<violation number="1" location="packages/docs/src/agent.ts:1502">
P3: This adds a duplicate YAML string serializer (`toDocsMarkdownYamlString`) even though `toYamlString` already exists in the same file. Reuse the existing helper to avoid two sources of truth.</violation>
</file>

<file name="packages/tanstack-start/src/server.ts">

<violation number="1" location="packages/tanstack-start/src/server.ts:1062">
P2: Derive the markdown metadata origin from the shared docs base-url resolver, not only `llmsTxt.baseUrl`, or these .md responses will advertise the wrong host when base URL is configured elsewhere.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Derive the markdown metadata origin from the shared docs base-url resolver, not only llmsTxt.baseUrl, or these .md responses will advertise the wrong host when base URL is configured elsewhere.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/tanstack-start/src/server.ts, line 1062:

<comment>Derive the markdown metadata origin from the shared docs base-url resolver, not only `llmsTxt.baseUrl`, or these .md responses will advertise the wrong host when base URL is configured elsewhere.</comment>

<file context>
@@ -1058,7 +1059,8 @@ export function createDocsServer(config: Record<string, any>): DocsServer {
     const markdownRequest = resolveDocsMarkdownRequest(entry, url, event.request);
     if (markdownRequest) {
-      const document = getMarkdownDocument(ctx, markdownRequest.requestedPath);
+      const markdownOrigin = llmsBaseUrl || url.origin;
+      const document = getMarkdownDocument(ctx, markdownRequest.requestedPath, markdownOrigin);
       const varyHeader = getDocsMarkdownVaryHeader(event.request);
</file context>

[cubic-dev-ai]

P3: This adds a duplicate YAML string serializer (toDocsMarkdownYamlString) even though toYamlString already exists in the same file. Reuse the existing helper to avoid two sources of truth.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/src/agent.ts, line 1502:

<comment>This adds a duplicate YAML string serializer (`toDocsMarkdownYamlString`) even though `toYamlString` already exists in the same file. Reuse the existing helper to avoid two sources of truth.</comment>

<file context>
@@ -1495,9 +1499,85 @@ function appendDocsMarkdownSitemapFooter(
   return `${markdown.replace(/\s+$/g, "")}\n\n${renderDocsMarkdownSitemapFooter(sitemap)}\n`;
 }
 
+function toDocsMarkdownYamlString(value: string): string {
+  return JSON.stringify(value);
+}
</file context>

Suggested change

	function toDocsMarkdownYamlString(value: string): string {
	return JSON.stringify(value);
	}
	const toDocsMarkdownYamlString = toYamlString;