@farming-labs/svelte 0.2.50 → 0.2.53

package/README.md

@@ -0,0 +1,73 @@
+# @farming-labs/svelte
+
+The SvelteKit runtime adapter for
+[`@farming-labs/docs`](https://www.npmjs.com/package/@farming-labs/docs).
+
+It loads Markdown, MDX, and SVX content, builds navigation, renders page content on the server, and
+provides SvelteKit handlers for docs, search, AI, agent discovery, MCP, and API references.
+
+## Package responsibilities
+
+- `@farming-labs/docs` — shared config, types, content features, and CLI
+- `@farming-labs/svelte` — SvelteKit content loading and server handlers
+- `@farming-labs/svelte-theme` — Svelte layout and UI components
+- `@farming-labs/theme` — shared preset CSS
+
+## Install
+
+The CLI can wire the complete SvelteKit integration:
+
+```bash
+npx @farming-labs/docs@latest init
+```
+
+For manual installation:
+
+```bash
+npm install @farming-labs/docs @farming-labs/svelte @farming-labs/svelte-theme @farming-labs/theme
+```
+
+## Server integration
+
+Preload content with Vite and create the docs server:
+
+```ts
+// src/lib/docs.server.ts
+import { createDocsServer } from "@farming-labs/svelte/server";
+import config from "./docs.config";
+
+const contentFiles = import.meta.glob("/docs/**/*.{md,mdx,svx}", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+}) as Record<string, string>;
+
+export const { load, GET, POST, MCP } = createDocsServer({
+  ...config,
+  _preloadedContent: contentFiles,
+});
+```
+
+Re-export `load` from the docs `+layout.server.ts` and `GET`/`POST` from the docs API route. Use
+`DocsLayout` and `DocsContent` from `@farming-labs/svelte-theme` for presentation. The CLI
+generates all of these files, including public agent and MCP forwarding.
+
+## Main entrypoints
+
+| Entrypoint | Purpose |
+| --- | --- |
+| `@farming-labs/svelte/server` | Docs server, loaders, API/MCP handlers, and API-reference helper |
+| `@farming-labs/svelte/content` | Content discovery and navigation utilities |
+| `@farming-labs/svelte/markdown` | Server-side Markdown rendering |
+| `@farming-labs/svelte/config` | Optional mdsvex configuration helper |
+| `@farming-labs/svelte/api-reference` | API-reference route handler |
+
+## Learn more
+
+- [Documentation](https://docs.farming-labs.dev/docs)
+- [SvelteKit example](https://github.com/farming-labs/docs/tree/main/examples/sveltekit)
+- [GitHub repository](https://github.com/farming-labs/docs)
+
+## License
+
+MIT

package/dist/content.d.ts

@@ -5,7 +5,7 @@
  * extracts frontmatter, and builds a navigation tree compatible
  * with @farming-labs/docs DocsConfig.
  */
-import { type OrderingItem, type ResolvedDocsRelatedLink, type SidebarFolderIndexBehavior } from "@farming-labs/docs";
+import { type OrderingItem, type PageAgentFrontmatter, type ResolvedDocsRelatedLink, type SidebarFolderIndexBehavior } from "@farming-labs/docs";
 export interface PageNode {
     type: "page";
     name: string;
@@ -32,9 +32,14 @@ export interface ContentPage {
     title: string;
     description?: string;
     related?: ResolvedDocsRelatedLink[];
+    agent?: PageAgentFrontmatter;
     icon?: string;
     sourcePath?: string;
     lastModified?: string;
+    locale?: string;
+    framework?: string;
+    version?: string;
+    tags?: string[];
     content: string;
     rawContent: string;
     agentContent?: string;

package/dist/content.js

@@ -8,7 +8,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { normalizeDocsRelated, resolveDocsAgentMdxContent, resolvePageSidebarFolderIndexBehavior, } from "@farming-labs/docs";
+import { normalizeDocsRelated, normalizePageAgentFrontmatter, resolveDocsAgentMdxContent, resolvePageSidebarFolderIndexBehavior, } from "@farming-labs/docs";
 /**
  * Scan a content directory and return all docs pages.
  * Expects a flat or nested structure of `.md` files:
@@ -52,9 +52,16 @@ export function loadDocsContent(contentDir, entry = "docs") {
                 title,
                 description: data.description,
                 ...(related.length > 0 ? { related } : {}),
+                agent: normalizePageAgentFrontmatter(data.agent),
                 icon: data.icon,
                 sourcePath: full.replace(/\\/g, "/"),
                 lastModified: stat.mtime.toISOString(),
+                locale: typeof data.locale === "string" ? data.locale : undefined,
+                framework: typeof data.framework === "string" ? data.framework : undefined,
+                version: typeof data.version === "string" ? data.version : undefined,
+                tags: Array.isArray(data.tags)
+                    ? data.tags.filter((tag) => typeof tag === "string")
+                    : undefined,
                 content: stripMarkdown(humanRawContent),
                 rawContent: humanRawContent,
                 ...(pageAgentRawContent !== humanRawContent

package/dist/server.js

@@ -30,7 +30,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { applySidebarFolderIndexBehavior, buildDocsAskAIContext, buildDocsAgentDiscoverySpec, buildDocsConfigMap, buildDocsDiagnostics, createDocsRobotsResponse, createDocsSitemapResponse, createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, findDocsMarkdownPage, getDocsLlmsTxtMaxCharsIssue, getDocsMarkdownCanonicalLinkHeader, getDocsMarkdownVaryHeader, isDocsAgentDiscoveryRequest, isDocsAgentsRequest, isDocsConfigRequest, isDocsDiagnosticsRequest, isDocsSkillRequest, normalizeDocsRelated, parseDocsAgentFeedbackData, performDocsSearch, renderDocsMarkdownDocument, renderDocsMarkdownNotFound, resolveDocsMarkdownRecovery, renderDocsLlmsTxt, renderDocsAgentsDocument, renderDocsSkillDocument, readDocsSitemapManifestFromContentMap, stripGeneratedAgentProvenance, resolveDocsAgentMdxContent, resolveDocsAgentFeedbackConfig, resolveDocsAgentFeedbackRequest, resolvePageSidebarFolderIndexBehavior, resolveAskAISearchRequestConfig, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsMetadataBaseUrl, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSitemapPageLastmod, resolveDocsAgentsFormat, resolveDocsSkillFormat, inferDocsTelemetryAgentSurface, renderDocsPageStructuredDataJson, selectDocsLlmsTxtContent, validateDocsAgentFeedbackPayload, } from "@farming-labs/docs";
+import { applySidebarFolderIndexBehavior, buildDocsAskAIContext, buildDocsAgentDiscoverySpec, buildDocsConfigMap, buildDocsDiagnostics, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, findDocsMarkdownPage, getDocsLlmsTxtMaxCharsIssue, isDocsAgentDiscoveryRequest, isDocsAgentsRequest, isDocsConfigRequest, isDocsDiagnosticsRequest, isDocsSkillRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, parseDocsAgentFeedbackData, performDocsSearch, renderDocsMarkdownDocument, renderDocsLlmsTxt, renderDocsAgentsDocument, renderDocsSkillDocument, readDocsSitemapManifestFromContentMap, stripGeneratedAgentProvenance, resolveDocsAgentMdxContent, resolveDocsAgentFeedbackConfig, resolveDocsAgentFeedbackRequest, resolvePageSidebarFolderIndexBehavior, resolveAskAISearchRequestConfig, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsMetadataBaseUrl, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSitemapPageLastmod, resolveDocsAgentsFormat, resolveDocsSkillFormat, inferDocsTelemetryAgentSurface, renderDocsPageStructuredDataJson, selectDocsLlmsTxtContent, validateDocsAgentFeedbackPayload, } from "@farming-labs/docs";
 import { buildApiReferenceOpenApiDocumentAsync, createDocsCloudAskAIResponse, createDocsMcpHttpHandler, isDocsCloudAskAIProvider, readDocsSitemapManifest, resolveApiReferenceConfig, resolveDocsMcpConfig, serializeDocsIconRegistry, serializeOpenDocsProviders, } from "@farming-labs/docs/server";
 import { loadDocsNavTree, loadDocsContent, flattenNavTree } from "./content.js";
 import { renderMarkdown } from "./markdown.js";
@@ -336,7 +336,14 @@ function searchIndexFromMap(contentMap, dirPrefix, entry) {
             title,
             description: data.description,
             ...(related.length > 0 ? { related } : {}),
+            agent: normalizePageAgentFrontmatter(data.agent),
             icon: data.icon,
+            locale: typeof data.locale === "string" ? data.locale : undefined,
+            framework: typeof data.framework === "string" ? data.framework : undefined,
+            version: typeof data.version === "string" ? data.version : undefined,
+            tags: Array.isArray(data.tags)
+                ? data.tags.filter((tag) => typeof tag === "string")
+                : undefined,
             content: stripMarkdownText(humanRawContent),
             rawContent: humanRawContent,
             ...(pageAgentRawContent !== humanRawContent
@@ -585,6 +592,7 @@ export function createDocsServer(config = {}) {
             baseUrl: resolveDocsMetadataBaseUrl(config),
             entry,
             dateModified: lastModifiedIso,
+            agent: normalizePageAgentFrontmatter(data.agent),
         });
         return {
             tree,
@@ -682,9 +690,14 @@ export function createDocsServer(config = {}) {
             return locale;
         return i18n.defaultLocale;
     }
-    function getMarkdownDocument(ctx, requestedPath, origin) {
+    function getMarkdownRepresentation(ctx, requestedPath, origin) {
         const page = findDocsMarkdownPage(entry, getSearchIndex(ctx), requestedPath);
-        return page ? renderDocsMarkdownDocument(page, { origin, sitemap: config.sitemap }) : null;
+        return page
+            ? {
+                document: renderDocsMarkdownDocument(page, { origin, sitemap: config.sitemap }),
+                lastModified: page.agentRawContent === undefined ? page.lastModified : undefined,
+            }
+            : null;
     }
     // ─── GET /api/docs?query=… | ?format=llms | ?format=llms-full ──
     async function GET(event) {
@@ -870,54 +883,17 @@ export function createDocsServer(config = {}) {
         const markdownRequest = resolveDocsMarkdownRequest(entry, event.url, event.request);
         if (markdownRequest) {
             const markdownOrigin = markdownMetadataBaseUrl || event.url.origin;
-            const document = getMarkdownDocument(ctx, markdownRequest.requestedPath, markdownOrigin);
-            const varyHeader = getDocsMarkdownVaryHeader(event.request);
-            const canonicalLinkHeader = getDocsMarkdownCanonicalLinkHeader({
-                origin: markdownOrigin,
+            const representation = getMarkdownRepresentation(ctx, markdownRequest.requestedPath, markdownOrigin);
+            return createDocsMarkdownResponse({
+                request: event.request,
+                document: representation?.document ?? null,
                 entry,
                 requestedPath: markdownRequest.requestedPath,
+                origin: markdownOrigin,
                 locale: ctx.locale,
-            });
-            if (!document) {
-                const recovery = resolveDocsMarkdownRecovery({
-                    entry,
-                    requestedPath: markdownRequest.requestedPath,
-                    pages: getSearchIndex(ctx),
-                    sitemap: config.sitemap,
-                });
-                if (recovery.redirect) {
-                    return new Response(null, {
-                        status: 307,
-                        headers: {
-                            Location: new URL(recovery.redirect.markdownUrl, event.url.origin).toString(),
-                            ...(varyHeader ? { Vary: varyHeader } : {}),
-                            "X-Robots-Tag": "noindex",
-                        },
-                    });
-                }
-                return new Response(renderDocsMarkdownNotFound({
-                    entry,
-                    requestedPath: markdownRequest.requestedPath,
-                    origin: markdownOrigin,
-                    pages: getSearchIndex(ctx),
-                    sitemap: config.sitemap,
-                }), {
-                    status: 200,
-                    headers: {
-                        "Content-Type": "text/markdown; charset=utf-8",
-                        ...(varyHeader ? { Vary: varyHeader } : {}),
-                        "X-Robots-Tag": "noindex",
-                    },
-                });
-            }
-            return new Response(document, {
-                headers: {
-                    "Content-Type": "text/markdown; charset=utf-8",
-                    "Cache-Control": "public, max-age=0, s-maxage=3600",
-                    Link: canonicalLinkHeader,
-                    ...(varyHeader ? { Vary: varyHeader } : {}),
-                    "X-Robots-Tag": "noindex",
-                },
+                lastModified: representation?.lastModified,
+                pages: getSearchIndex(ctx),
+                sitemap: config.sitemap,
             });
         }
         const llmsRequest = resolveDocsLlmsTxtRequest(event.url, llmsTxtConfig, entry);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/svelte",
-  "version": "0.2.50",
+  "version": "0.2.53",
   "description": "SvelteKit adapter for @farming-labs/docs — content loading and navigation utilities",
   "keywords": [
     "docs",
@@ -56,7 +56,7 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.9.3",
-    "@farming-labs/docs": "0.2.50"
+    "@farming-labs/docs": "0.2.53"
   },
   "peerDependencies": {
     "@farming-labs/docs": "*"