@lupinum/ginko-content 0.1.0 → 0.1.2

package/README.md

@@ -1,61 +1,80 @@
 # @lupinum/ginko-content
 
-Filesystem-first, provider-neutral content for Nuxt 4.
+Filesystem-first content for Nuxt 4.
 
-`@lupinum/ginko-content` gives you:
+Write Markdown and data files in `content/`, define collections once in
+`content.config.ts`, then use those collection handles for route pages, lists,
+navigation, search, i18n, and sitemap output.
 
-- file-authored pages and navigation from `content/`
-- required typed collections via `content.config.ts`
-- Markdown, MDC, YAML, JSON, and CSV ingestion
-- locale-aware content routing
-- built-in search endpoints and first-class search composables
-- a server-side provider contract for advanced custom sources
+Use it when you want content files to stay simple, but your Nuxt app still
+needs explicit APIs for route resolution, typed frontmatter, localized content,
+and server-side reads.
+
+## Requirements
+
+- Node.js 20 or later
+- Nuxt 4.0 or later
 
 ## Install
 
 ```bash
-pnpm add @lupinum/ginko-content zod
+npx nuxi module add @lupinum/ginko-content
 ```
 
-Add the module to your `nuxt.config.ts`:
+The Nuxt CLI installs the package and registers the module in `nuxt.config.ts`.
+If you prefer to install by hand:
+
+```bash
+pnpm add @lupinum/ginko-content
+```
 
 ```ts
 export default defineNuxtConfig({
-  modules: ['@lupinum/ginko-content']
+  modules: ['@lupinum/ginko-content'],
+  imports: {
+    autoImport: true
+  }
 })
 ```
 
-Ginko is published as `@lupinum/ginko-content` and should be registered under that package name.
+## Quick Start
 
-The default provider reads files from your Nuxt project. The package does not include a CMS UI, Studio, admin panel, or content editing workflow.
+Define a collection:
 
-## Compatibility
+```ts
+// content.config.ts
+import { defineCollection, defineContentConfig } from '@lupinum/ginko-content/config'
 
-`@lupinum/ginko-content@2.13.4` targets Nuxt `>=4.0.0` and is verified against
-Nuxt `4.4.6`. It is compatible with the first Ginko CMS release line:
-`@lupinum/ginko-cms@0.1.0`, `@lupinum/ginko-cms-convex@0.1.0`, and
-`@lupinum/ginko-cms-contract@0.1.0`.
+export const pages = defineCollection({
+  type: 'page',
+  source: '**/*.md'
+})
+
+export default defineContentConfig({
+  collections: {
+    pages
+  }
+})
+```
 
-The CMS boundary uses `./cms-contract` and `./cms-import`. Those subpaths are
-runtime-neutral seams for package integration, not a bundled CMS runtime.
+Create `content/index.md`:
 
-## Basic usage
+```md
+---
+title: Welcome
+---
 
-Create content files:
+# Welcome
 
-```text
-content/
-  index.md
-  guide/getting-started.md
+This file renders at `/`.
 ```
 
-Render content in a catch-all page:
+Render the current route through the collection:
 
 ```vue
+<!-- pages/[...slug].vue -->
 <script setup lang="ts">
-import { pages } from '~/content.config'
-
-const { page } = await useContentPage(pages)
+const { page } = await useContentPage('pages')
 </script>
 
 <template>
@@ -63,28 +82,55 @@ const { page } = await useContentPage(pages)
 </template>
 ```
 
-Define the collection in `content.config.ts`:
+## Features
 
-```ts
-import { defineCollection, defineContentConfig, fields } from '@lupinum/ginko-content/config'
-import { z } from 'zod'
+- file-authored pages and navigation from `content/`
+- collection definitions as the source of truth for content shape and source
+  files
+- Markdown, Comark component tags, YAML, JSON, and CSV ingestion
+- locale-aware content routing
+- route-aware page loading with `useContentPage('pages')`
+- semantic previous/next route-page data through `useContentPage('pages', { surround })`
+- server reads through `one`, `many`, `paginate`, `resolveOne`, `tree`, and
+  `neighbors`
+- Vue composables for the same read model
+- search helpers for MiniSearch, Pagefind, and provider-owned search
+- sitemap integration for public content routes
+- a server-side provider contract for advanced custom sources
 
-export const pages = defineCollection('pages', {
-  type: 'page',
-  source: ['index.md', 'guide/**/*.md'],
-  schema: z.object({
-    title: fields.text()
-  })
-})
+## I18n, Sitemap, and Prerender Ownership
 
-export default defineContentConfig({
-  collections: {
-    pages
-  }
-})
-```
+For localized Nuxt apps, keep one source of truth per route type:
+
+- Static Nuxt page paths belong in Nuxt I18n `i18n.pages`.
+- Content page paths belong in Ginko collection routes and content files.
+- Sitemap XML is generated by `@nuxtjs/sitemap`.
+- Ginko registers the content sitemap source and contributes content prerender
+  routes.
+
+Do not duplicate docs, blog, pricing, privacy, or translated locale paths in
+`sitemap.urls` or app-owned `nitro.prerender.routes` arrays. Use
+`@nuxtjs/sitemap >= 8.0.15` when translated static app slugs such as `/preise`
+and `/en/pricing` need cross-locale sitemap alternates.
+
+See the public guide: [Sitemap and prerender](../../docs/content/docs/6.i18n/4.sitemap-prerender.md).
+
+## Scope
+
+The default provider reads files from your Nuxt project. The package does not
+include a CMS UI, Studio, admin panel, or content editing workflow.
 
 ## Docs
 
 - Documentation: [ginko-content.nuxt.dev](https://ginko-content.nuxt.dev)
 - Repository: [github.com/lupinum-dev/ginko-content](https://github.com/lupinum-dev/ginko-content)
+
+## Credits
+
+Ginko Content is its own implementation, with clear inspiration from
+[Nuxt Content](https://content.nuxt.com/), [Nuxt UI](https://ui.nuxt.com/), and
+[Comark](https://comark.dev/), the successor to the previous MDC work.
+
+## License
+
+[MIT](./LICENSE)

package/compatibility.json

@@ -1,10 +1,10 @@
 {
   "name": "Ginko Content release compatibility",
   "releaseStack": {
-    "@lupinum/ginko-content": "0.1.0",
-    "@lupinum/ginko-cms": "0.1.0",
-    "@lupinum/ginko-cms-convex": "0.1.0",
-    "@lupinum/ginko-cms-contract": "0.1.0"
+    "@lupinum/ginko-content": "0.1.2",
+    "@lupinum/ginko-cms": "0.1.2",
+    "@lupinum/ginko-cms-convex": "0.1.1",
+    "@lupinum/ginko-cms-contract": "0.1.1"
   },
   "tracked": {
     "@convex-dev/better-auth": ["^0.12.2", "0.12.2"],
@@ -13,7 +13,7 @@
     "convex": ["1.38.0", "^1.38.0"],
     "convex-helpers": ["^0.1.117", "0.1.117"],
     "h3": ["1.15.11"],
-    "nuxt": ["^4.4.6", "4.4.6", ">=4.0.0"],
+    "nuxt": ["^4.4.7", "4.4.7", ">=4.4.7"],
     "typescript": ["~6.0.3", "^6.0.3", "6.0.3"],
     "vite": ["^7.3.3", "7.3.3"],
     "vitest": ["^4.1.6", ">=4.1.6"],

package/dist/cli.mjs

@@ -42,32 +42,27 @@ const sourceChecks = [
   {
     pattern: /\bqueryCollectionItemSurroundings\s*\(/,
     message: "Nuxt Content v3 surround helper found.",
-    suggestion: "Use useContentNeighbors(handle, { by: { route } }) in route page components."
+    suggestion: "Use useContentPage('docs', { surround: true }) in route page components."
   },
   {
     pattern: /\bqueryCollectionSearchSections\s*\(/,
     message: "Nuxt Content v3 search sections helper found.",
-    suggestion: "Use useContentSearchData(collection) for UI search data."
+    suggestion: "Use useContentSearchData('docs') for UI search data."
   },
   {
     pattern: /\bqueryCollectionNavigation\s*\(/,
     message: "Nuxt Content v3 navigation helper found.",
-    suggestion: "Use useContentTree(handle) for layout navigation."
+    suggestion: "Use useContentNavigation('docs') for layout navigation."
   },
   {
     pattern: /\bqueryCollection\s*\(/,
     message: "Removed collection query helper found.",
-    suggestion: "Use one(handle, options), many(handle, options), paginate(handle, options), or the matching useContent* composable."
+    suggestion: "Use one('docs', options), many('docs', options), paginate('docs', options), or the matching useContent* composable."
   },
   {
     pattern: /\buseContentList\s*\(/,
     message: "Removed content list composable found.",
-    suggestion: "Use useContentMany(handle, options) or many(handle, options)."
-  },
-  {
-    pattern: /\buseContentNavigation\s*\(/,
-    message: "Removed content navigation composable found.",
-    suggestion: "Use useContentTree(handle) for layout navigation."
+    suggestion: "Use useContentMany('docs', options) or many('docs', options)."
   },
   {
     pattern: /\bcontent\.(database|preview|build)\b/,
@@ -84,21 +79,158 @@ const sourceChecks = [
     message: "ContentRenderer is receiving a document body.",
     suggestion: "Pass the full content document to ContentRenderer, not document.body."
   },
-  {
-    pattern: /<NuxtLink\b[^>]*:to\s*=\s*["'][^"']+\.path["']/,
-    message: "NuxtLink may be using raw query .path.",
-    suggestion: "Use useContentMany(handle, options) for route-safe list items, or link route-page payloads with their explicit path field."
-  },
   {
     pattern: /<NuxtLink\b[^>]*:to\s*=\s*["'][^"']+\._path["']/,
     message: "NuxtLink is using raw content _path.",
-    suggestion: "Use useContentMany(handle, options) for list pages and bind the route-safe item.path field."
+    suggestion: "Use useContentMany('docs', options) for list pages and bind the route-safe item.path field."
   }
 ];
 const lockfileNames = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"];
 const localeCodePattern = /^[a-z]{2}(?:-[A-Z]{2})?$/;
 const toRelativePath = (rootDir, file) => relative(rootDir, file) || ".";
 const countSitemapUrls = (text) => (text.match(/<url>/g) || []).length;
+function findMatchingBrace(text, start) {
+  let depth = 0;
+  let quote;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+  for (let index = start; index < text.length; index++) {
+    const char = text[index];
+    const next = text[index + 1];
+    if (lineComment) {
+      if (char === "\n") {
+        lineComment = false;
+      }
+      continue;
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        index++;
+      }
+      continue;
+    }
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        quote = void 0;
+      }
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      index++;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      index++;
+      continue;
+    }
+    if (char === "'" || char === '"' || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "{") {
+      depth++;
+    } else if (char === "}") {
+      depth--;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return text.length - 1;
+}
+function findAuthoredCollectionDefinitions(text) {
+  const definitions = /* @__PURE__ */ new Map();
+  const callPattern = /\bdefineCollection\s*\(/g;
+  for (const match of text.matchAll(callPattern)) {
+    const callStart = match.index || 0;
+    const argsStart = callStart + match[0].length;
+    const args = text.slice(argsStart);
+    const objectMatch = args.match(/^\s*\{/);
+    if (!objectMatch) {
+      continue;
+    }
+    const bodyStart = argsStart + objectMatch[0].lastIndexOf("{");
+    const bodyEnd = findMatchingBrace(text, bodyStart);
+    const block = text.slice(bodyStart, bodyEnd + 1);
+    const prefix = text.slice(0, callStart);
+    const propertyMatch = prefix.match(/([a-z_$][\w$]*)\s*:\s*$/i);
+    if (propertyMatch) {
+      definitions.set(propertyMatch[1], {
+        key: propertyMatch[1],
+        block
+      });
+      continue;
+    }
+    const variableMatch = prefix.match(/(?:^|[\s;])(?:export\s+)?(?:const|let|var)\s+([a-z_$][\w$]*)\s*=\s*$/i);
+    if (variableMatch) {
+      definitions.set(variableMatch[1], { block });
+    }
+  }
+  return definitions;
+}
+function findCollectionDefinitions(text) {
+  const authoredCollections = findAuthoredCollectionDefinitions(text);
+  const definitions = /* @__PURE__ */ new Map();
+  for (const block of findObjectPropertyBlocks(text, "collections")) {
+    for (const match of block.matchAll(/([a-z_$][\w$]*)\s*:\s*([a-z_$][\w$]*)\b/g)) {
+      const [, key, identifier] = match;
+      const authored = authoredCollections.get(identifier);
+      if (authored) {
+        definitions.set(key, {
+          name: key,
+          block: authored.block
+        });
+      }
+    }
+    for (const match of block.matchAll(/(?:^|[,{]\s*)([a-z_$][\w$]*)\s*(?=,|\})/g)) {
+      const key = match[1];
+      const authored = authoredCollections.get(key);
+      if (authored) {
+        definitions.set(key, {
+          name: key,
+          block: authored.block
+        });
+      }
+    }
+  }
+  for (const authored of authoredCollections.values()) {
+    if (authored.key) {
+      definitions.set(authored.key, {
+        name: authored.key,
+        block: authored.block
+      });
+    }
+  }
+  return [...definitions.values()];
+}
+function findObjectPropertyBlocks(text, property) {
+  const blocks = [];
+  const pattern = new RegExp(`\\b${property}\\s*:\\s*\\{`, "g");
+  for (const match of text.matchAll(pattern)) {
+    const bodyStart = text.indexOf("{", match.index);
+    if (bodyStart === -1) {
+      continue;
+    }
+    const bodyEnd = findMatchingBrace(text, bodyStart);
+    blocks.push(text.slice(bodyStart, bodyEnd + 1));
+  }
+  return blocks;
+}
+function extractStringArrayProperty(block, property) {
+  const match = block.match(new RegExp(`\\b${property}\\s*:\\s*\\[([\\s\\S]*?)\\]`));
+  if (!match) {
+    return [];
+  }
+  return [...match[1].matchAll(/['"]([^'"]+)['"]/g)].map((item) => item[1]);
+}
 async function collectFiles(dir, rootDir, files = []) {
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
@@ -174,6 +306,32 @@ async function inspectSourceFiles(rootDir) {
   }
   return findings;
 }
+async function inspectSearchCollections(rootDir) {
+  const contentConfig = await readTextIfPresent(join(rootDir, "content.config.ts"));
+  const nuxtConfig = await readTextIfPresent(join(rootDir, "nuxt.config.ts"));
+  if (!contentConfig || !nuxtConfig) {
+    return [];
+  }
+  const dataCollections = new Set(
+    findCollectionDefinitions(contentConfig).filter((collection) => /\btype\s*:\s*['"]data['"]/.test(collection.block)).map((collection) => collection.name)
+  );
+  if (!dataCollections.size) {
+    return [];
+  }
+  const configuredCollections = new Set(
+    findObjectPropertyBlocks(nuxtConfig, "search").flatMap((block) => extractStringArrayProperty(block, "collections"))
+  );
+  const dataSearchCollections = [...configuredCollections].filter((collection) => dataCollections.has(collection));
+  if (!dataSearchCollections.length) {
+    return [];
+  }
+  return [{
+    severity: "info",
+    file: "nuxt.config.ts",
+    message: `Data-only collections listed in content.search.collections: ${dataSearchCollections.join(", ")}.`,
+    suggestion: "Remove data-only collections from the static public search index, make them route-backed pages, or use provider-backed search with route-safe results."
+  }];
+}
 async function inspectLockfiles(rootDir) {
   const findings = [];
   for (const lockfileName of lockfileNames) {
@@ -372,25 +530,21 @@ async function inspectI18nCollections(rootDir) {
       suggestion: "Declare i18n collections with defineContentConfig({ collections })."
     }];
   }
-  const matches = [...text.matchAll(/([A-Za-z_$][\w$]*)\s*:\s*defineCollection\s*\(\s*\{/g)];
-  if (!matches.length) {
+  const collections = findCollectionDefinitions(text);
+  if (!collections.length) {
     return [];
   }
   const findings = [];
-  matches.forEach((match, index) => {
-    const collectionName = match[1];
-    const start = match.index || 0;
-    const end = matches[index + 1]?.index || text.length;
-    const collectionBlock = text.slice(start, end);
-    if (!/\bi18n\s*:\s*(true|\{)/.test(collectionBlock)) {
+  for (const collection of collections) {
+    if (!/\bi18n\s*:\s*(true|\{)/.test(collection.block)) {
       findings.push({
         severity: "error",
         file: "content.config.ts",
-        message: `Collection "${collectionName}" is not marked as i18n-aware.`,
-        suggestion: `Add i18n: true to the ${collectionName} collection or provide collection-level i18n locales.`
+        message: `Collection "${collection.name}" is not marked as i18n-aware.`,
+        suggestion: `Add i18n: true to the ${collection.name} collection or provide collection-level i18n locales.`
       });
     }
-  });
+  }
   return findings;
 }
 async function inspectI18nContentFolders(rootDir, locales) {
@@ -427,7 +581,7 @@ async function inspectI18nSourceSmells(rootDir, locales) {
         severity: "error",
         file: relativeFile,
         message: "Hardcoded locale route branch found.",
-        suggestion: "Use @nuxtjs/i18n route helpers, useContentTree(handle), or useContentMany(handle, options) item paths instead of branching on locale codes."
+        suggestion: "Use @nuxtjs/i18n route helpers, useContentNavigation('docs'), or useContentMany('docs', options) item paths instead of branching on locale codes."
       });
     }
     if (/<(?:NuxtLink|U[A-Za-z]+)\b[^>]*:to\s*=\s*["'][^"']+\._path["']/.test(text)) {
@@ -435,7 +589,7 @@ async function inspectI18nSourceSmells(rootDir, locales) {
         severity: "error",
         file: relativeFile,
         message: "UI link is bound to raw content _path.",
-        suggestion: "Use useContentMany(handle, options) for localized list pages and bind item.path."
+        suggestion: "Use useContentMany('docs', options) for localized list pages and bind item.path."
       });
     }
   }
@@ -620,6 +774,7 @@ async function runDoctor(options = {}) {
   const findings = [
     ...await inspectPackageJson(rootDir),
     ...await inspectSourceFiles(rootDir),
+    ...await inspectSearchCollections(rootDir),
     ...await inspectLockfiles(rootDir),
     ...await inspectSitemap(rootDir),
     ...options.i18n ? await inspectI18n(rootDir) : []

package/dist/core/references/schema.d.ts

@@ -5,4 +5,5 @@ export declare const getObjectShape: (schema: any) => Record<string, any>;
 export declare const getReferenceDescriptor: (schema: any) => {
     collection?: string;
 } | null;
+export declare const collectTopLevelReferenceFieldsByTarget: (schema: unknown) => Record<string, string[]>;
 export declare const collectTopLevelReferenceFields: (schema: unknown, targetCollection?: string) => string[];

package/dist/core/references/schema.js

@@ -53,18 +53,41 @@ const getArrayElement = (schema) => {
   const def = getSchemaDef(current);
   return def.element || def.type || null;
 };
-export const collectTopLevelReferenceFields = (schema, targetCollection) => {
+const wildcardReferenceTarget = "*";
+const getTopLevelReferenceDescriptor = (schema) => {
+  const direct = getReferenceDescriptor(schema);
+  if (direct) {
+    return direct;
+  }
+  const arrayElement = getArrayElement(schema);
+  return arrayElement ? getReferenceDescriptor(arrayElement) : null;
+};
+export const collectTopLevelReferenceFieldsByTarget = (schema) => {
   const current = unwrapSchema(schema);
   if (getSchemaTypeName(current) !== "ZodObject") {
-    return [];
+    return {};
   }
-  return Object.entries(getObjectShape(current)).filter(([, childSchema]) => {
-    const direct = getReferenceDescriptor(childSchema);
-    if (direct) {
-      return !direct.collection || !targetCollection || direct.collection === targetCollection;
+  const references = {};
+  for (const [field, childSchema] of Object.entries(getObjectShape(current))) {
+    const descriptor = getTopLevelReferenceDescriptor(childSchema);
+    if (!descriptor) {
+      continue;
     }
-    const arrayElement = getArrayElement(childSchema);
-    const arrayRef = arrayElement ? getReferenceDescriptor(arrayElement) : null;
-    return Boolean(arrayRef && (!arrayRef.collection || !targetCollection || arrayRef.collection === targetCollection));
-  }).map(([field]) => field);
+    const target = descriptor.collection || wildcardReferenceTarget;
+    references[target] ||= [];
+    references[target].push(field);
+  }
+  return references;
+};
+export const collectTopLevelReferenceFields = (schema, targetCollection) => {
+  const references = collectTopLevelReferenceFieldsByTarget(schema);
+  if (!targetCollection) {
+    return [...new Set(Object.values(references).flat())];
+  }
+  return [
+    .../* @__PURE__ */ new Set([
+      ...references[targetCollection] || [],
+      ...references[wildcardReferenceTarget] || []
+    ])
+  ];
 };

package/dist/integrations/nitro/context.d.ts

@@ -13,14 +13,13 @@
  *
  * The context is attached to `event.context.__contentRuntime` and created
  * lazily on first access. Memoization uses `memoizeRuntimeValue` so the
- * `graph` / `contents` caches are shared across helpers within a single
+ * expensive per-request values are shared across helpers within a single
  * request but torn down with the event.
  */
 import type { H3Event } from 'h3';
 import type { Storage } from 'unstorage';
 import type { ParsedContent } from '../../types/content';
 import type { ContentContext as RuntimeContentConfig } from '../../types/module';
-import type { ContentGraph } from '../../core/content/graph';
 import type { ContentCacheStore } from '../../core/cache';
 import type { ContentCacheHint } from '../../public/provider';
 /**
@@ -41,16 +40,13 @@ export interface ContentRuntimeContext {
         cacheStorage: Storage;
         cacheParsedStorage: Storage;
     };
-    memo: {
-        contents?: ParsedContent[] | Promise<ParsedContent[]>;
-        graph?: ContentGraph | Promise<ContentGraph>;
-    };
+    memo: Record<string, unknown | Promise<unknown> | undefined>;
     caches?: ContentCacheStore<ParsedContent>;
     cacheHint?: ContentCacheHint | false;
 }
 export declare const getContentRuntimeContext: (event: H3Event) => ContentRuntimeContext;
 /**
- * Memoize an expensive per-request value (typically `contents` or `graph`).
+ * Memoize an expensive per-request value.
  *
  * Concurrent callers within a single request that hit the same key all await
  * the one `create()` promise — we do not start a second compute. The cache
@@ -60,4 +56,4 @@ export declare const getContentRuntimeContext: (event: H3Event) => ContentRuntim
  * you cannot use this helper — mutate `runtime.memo[key]` directly. In
  * practice, nothing we build mid-request invalidates the graph.
  */
-export declare const memoizeRuntimeValue: <T>(event: H3Event, key: keyof ContentRuntimeContext["memo"], create: () => Promise<T>) => Promise<T>;
+export declare const memoizeRuntimeValue: <T>(event: H3Event, key: string, create: () => Promise<T>) => Promise<T>;