@lupinum/ginko-content 0.4.0-rc.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# @lupinum/ginko-content
+
+## 0.4.0
+
+### Minor Changes
+
+- [`ea2ea13`](https://github.com/lupinum-dev/ginko/commit/ea2ea133997f2011ad0d43f77a0f1dc75605923e) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add Ginko 0.4, the first release: one content system for Nuxt websites, from Markdown files in Git to a hosted platform.
+  
+  Owners, staff and AI agents edit the same content. All seven packages release together under one version. It starts at 0.4 because `@lupinum/ginko-content` and `@lupinum/ginko-docs` already published an older, unrelated line up to 0.3. Until 1.0, a minor version (0.4 → 0.5) may contain breaking changes; the changelog names each one and how to update.
+  
+  Requirements: Node 22.18+, 24 or 26, and Nuxt 4.6+ or Nuxt 5 (tested on its nightly until it is released). Start a site with `npm create ginko@latest my-site`; the documentation explains every step.
+  
+  **Public API**
+  
+  - `@lupinum/ginko`: `defineSite`, `single`, `collection`, `f`, `defineComponents`, `formatMoney`, `plainText`, `safeHref`, `startOfWeek` and the documented types. Imported, not auto-imported.
+  - `@lupinum/ginko/nuxt`: the module, the `useGinko*` composables (everything that needs a Nuxt app starts with `useGinko`), `<GinkoMarkdown>` and `<GinkoImage>`. `@lupinum/ginko/vue`: `<GinkoMarkdown>` for any Vue app. `@lupinum/ginko/search`: `loadIndex` and `search`.
+  - `@lupinum/ginko/internal` and `@lupinum/ginko/internal/search` are for Ginko's own packages and have no stability promise.
+  - The `ginko` CLI: `check [--offline]`, `release` and `export [folder]`, plus `--version`. Every command run prints one JSON line, `{ "ok": true, … }` or `{ "ok": false, "error": { code, message } }` (`--help` and `--version` print plain text), and ends with exit code 0 (ok), 1 (fix the code), 2 (usage), 3 (platform unreachable, retry) or 4 (key not allowed). CI deploys the site only when `release` prints `"deploy": true` (a superseded run exits 0 with `"deploy": false`). The CLI reads `GINKO_PLATFORM` (or `NUXT_PUBLIC_GINKO_PLATFORM`), `GINKO_KEY`, `GINKO_COMMIT` (or `GITHUB_SHA`), `GINKO_BRANCH` and `GINKO_REMOTE`; it does not read `.env` files. `ginko-i18n --json` uses the same output shape, error codes (`USAGE`, `INVALID`) and exit codes.
+  - Config names: `f.ref` (one entry) and `f.refs` (several); `visible: { mode: 'until', field, days?, deleteExpired? }`; prefill tokens `@today`, `@workWeek`, `@nextWorkWeek`; `firstDayOfWeek`, `linkCheck`, `untranslated`, `maxBytes`, `Migration.compute`, `retired` rule `{ drop: true }`. Options and defaults are typed per field, and an unknown top-level key fails the build.
+  - Markdown components: `embed`, `frame` (`none`, `card`, `border`, …), `background` (`none`, `muted`, `tint`), `appearance` (`quiet`, `tint`), `quiz-question{mode}`, `code-tree{file}`.
+  
+  **Content (`@lupinum/ginko`, `@lupinum/ginko-content`)**
+  
+  - One text format: Markdown (comark 0.7) everywhere, with field profiles that limit what a field may contain. Footnotes, emoji, alerts, Shiki code, task lists, route links (`$blog.my-post`), reusable snippets and heading anchors.
+  - Data files: YAML and JSON (one file, one entry) and CSV (one file, many entries), checked against the field schema; every error names the file and field, and the line for CSV rows and unreadable files. Entries with `draft: true` stay out of production builds.
+  - Query engine in the site, over the loaded bundle: `where`, `order`, `limit`, pagination with totals, field selection, `include` for references, previous/next and facet counts.
+  - References (`f.ref`, `f.refs`), navigation trees and breadcrumbs, and a URL for every entry in every language; two entries on one URL fail the build.
+  - Link check before any HTML exists: route links, anchors, snippets and redirected paths, in the build, the dev terminal, `ginko check` and the agent tools. On the platform a save, a new entry or a scheduled publish that adds a broken link is stopped, and History says why. External links are checked on request (`linkCheck.external`), at build and in `ginko check` (never in dev), with a 7-day cache.
+  - Images: WebP copies at 480, 960 and 1600 px, made at upload on the platform and at build for files. `<GinkoImage>` and Markdown images get `srcset` and `sizes`.
+  - Redirects from `redirectFrom` (301) and site rules in `redirects` (301 by default, `status` 302/307/308 per rule).
+  - SEO from the bundle, with no other module: title template, canonical, Open Graph with `og:url`, `<html lang>`, hreflang with `x-default`, sitemap with `lastmod`, images and alternates, robots.txt with `noindex` on preview hosts, JSON-LD. With `nuxt-og-image` (in every starter), every page gets a generated share card in the brand colour `seo.color`, with the site's logo and the page's image.
+  - Works with the Nuxt SEO modules (`@nuxtjs/seo` or single ones, in any order): Ginko leaves them sitemap, robots.txt and JSON-LD defaults and hands them its pages with hreflang, the site's address, name and languages, and `noindex` on preview hosts. `nuxt-ai-ready` stays off while Ginko serves `/llms.txt`. Requires `nuxt-og-image` 7.
+  - Search index built in plain JS at build time, one record per heading section, loaded lazily per language.
+  - Agent output: `/llms.txt`, `/llms-full.txt`, a `.md` twin for every entry page (collections with a `route`), and a Markdown 404 that suggests pages. The normal address always answers with HTML.
+  - Render modes: Git-only sites prerender everything; platform sites refresh changed pages after a publish; previews render with `noindex`.
+  - In dev, `nuxt dev` restarts when `ginko.config.ts` changes, and a brick that cannot reach the platform names itself and the fix.
+  - CLI `ginko`: `check` (schema, links and the share image, for every site; `--offline` without the platform) and `release` for CI, `export` for backups; `pnpm local:dev|import|pull` run only in the Ginko monorepo.
+  
+  **Languages (`@lupinum/ginko-i18n`)**
+  
+  - The only locale authority: routes, alternates, hreflang, messages with plurals, and formatters for dates, ranges, relative time, numbers, currency and lists, each in the site's time zone.
+  - Works on its own in any Nuxt 4.6+ or Nuxt 5 app, without the rest of Ginko.
+  
+  **Components and docs (`@lupinum/ginko-components`, `@lupinum/ginko-docs`)**
+  
+  - Content components with props defined as Ginko fields: callouts, tabs, code groups, steps, cards, accordion, figures, embeds (click to load), timeline, quiz and more. Each one can also be copied into an app with the shadcn-vue CLI, from a registry the docs build generates.
+  - Docs layer (`@lupinum/ginko-docs`; `npm create ginko@latest my-docs -- --preset docs` starts a site with it): navigation, section tabs, breadcrumbs, table of contents with scroll spy, previous/next, ⌘K search with heading results, blog with authors and RSS, changelog, copy page as Markdown, dark mode. A guide for switching from Nuxt Content and `@nuxtjs/i18n`. Math (KaTeX) and mermaid diagrams render and load only on pages that use them.
+  
+  **Platform and Studio (hosted by Lupinum)**
+  
+  The platform is a hosted service, not an npm package. A site connects to it with one setting; without it, the site reads its content from files.
+  
+  - Quick tasks for the jobs owners do most ("Heute geschlossen", "Preis ändern"), phone first, with the full form behind "Alles bearbeiten".
+  - Files library: All, Recent, Unused, Missing alt text, Duplicates and folders; icon and list views; "used in" with links; replace a file and keep its references; a used file cannot be removed by mistake. Alt text set in the library is the default for every use, per language.
+  - Approvals, off by default: a task or agent key can need a yes. Reviewers see the change, approve, approve for a time, or reject with a sentence; the author sees the reason. Releases publish several changes together.
+  - History with "show changes", "back to this version" and undo; drafts and scheduled publishing; trash with restore; translation status per language; "why is this not on the website?".
+  - Team and invitations with per-task rights, sign-in with an emailed code, AI agent keys with an MCP tool catalog derived from the operations, and weekly reminder mails.
+  - Long forms group their fields under headings or in tabs (`group` on a field, `layout: 'tabs'` on a brick); phones always show headings.
+  - A rich text editor (TipTap 3) that writes Markdown, where untouched text stays byte for byte. Headings, lists, task lists, quotes, code blocks, tables, images from the library, embeds, registry components with prop forms, slash and bubble menus, Markdown shortcuts and paste, source mode, find and replace (⌘F), a drag handle and Alt+↑/↓ to move blocks, character counter, a link card for pasted URLs, uploads with progress, and a formatting bar above the phone keyboard.
+  - Delete a site, with seven days to cancel, and delete your own account. The last owner of a site must hand it over or delete it first.
+  - Studio in German, English and Spanish (beta), light and dark.
+  
+  **Presets (`@lupinum/ginko-preset-gastro`, `create-ginko`)**
+  
+  - Gastro: opening hours with exceptions, seasons, holidays and new hours from a date; lunch week with planning ahead and an optional PDF; menu with prices from a date; notices that expire; events; JSON-LD for Restaurant, Menu, opening hours and Event; a printable lunch sheet.
+  - `create-ginko` starts a new site, plain or with `--preset gastro|docs`. Starters install with npm, pnpm 11 and bun, carry a `typecheck` script, a page description and share cards (`nuxt-og-image` with Takumi, Nuxt 4.6.1 or later; set `NUXT_APP_SECRET` where the site runs, `.env` has one), and create-ginko warns on an unsupported Node.
+  
+  **Not in 0.4**
+  
+  Real-time co-editing comes next. Also not included: an agency preset, the editor UI as a shadcn-vue registry, OAuth for agent connectors, and a Google Business sync.
+
+### Patch Changes
+
+- Updated dependencies [[`ea2ea13`](https://github.com/lupinum-dev/ginko/commit/ea2ea133997f2011ad0d43f77a0f1dc75605923e)]:
+  - @lupinum/ginko@0.4.0

package/LICENSE

@@ -1,7 +1,6 @@
 MIT License
 
-Copyright (c) 2026-present Lupinum OG
-Copyright (c) Nuxt Project
+Copyright (c) 2025-2026 Lupinum OG
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,173 +1,48 @@
 # @lupinum/ginko-content
 
-Filesystem-first content for Nuxt 4.
+Files as a content source for [`@lupinum/ginko`](https://github.com/lupinum-dev/ginko/tree/main/packages/ginko).
+At build time it reads `content/` and builds the same bundle the Ginko platform serves, so a site
+reads files and platform content the same way, with `useGinko`. Use it for content that developers
+maintain: docs, a blog, legal pages, a price list. It reads Markdown, YAML, JSON and CSV.
 
-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.
-
-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.
-
-This README describes the `0.4.0-rc.1` release candidate. Install it from npm's
-`next` channel; the stable line remains `0.3` until the RC is promoted.
-
-## Requirements
-
-- Node.js 22.18–22.x, 24.11–24.x, or 26+
-- Nuxt 4.4.7 through Nuxt 4.x
-- Vue 3.5.35 through Vue 3.x
-- ESM; CommonJS `require()` is not supported
-
-## Install
-
-```bash
-npx nuxi module add @lupinum/ginko-content@0.4.0-rc.1
-```
-
-The Nuxt CLI installs the package and registers the module in `nuxt.config.ts`.
-If you prefer to install by hand:
+## Use
 
 ```bash
-pnpm add @lupinum/ginko-content@0.4.0-rc.1
+npm install @lupinum/ginko @lupinum/ginko-content
 ```
 
-```ts
-export default defineNuxtConfig({
-  modules: ['@lupinum/ginko-content'],
-  imports: {
-    autoImport: true
-  }
-})
-```
-
-## Quick Start
+`@lupinum/ginko` is a peer dependency. Images get WebP variants through `sharp`, an optional peer dependency: install it
+(`npm install sharp`, version 0.33 to 0.35) if your site has image files. `ginko check` runs without it.
 
-Define a collection:
+Give a brick `source: 'files'` and one `f.markdown` field:
 
 ```ts
-// content.config.ts
-import { defineCollection, defineContentConfig } from '@lupinum/ginko-content/config'
-
-export const pages = defineCollection({
-  type: 'page',
-  source: '**/*.md'
-})
-
-export default defineContentConfig({
-  collections: {
-    pages
-  }
-})
-```
-
-Create `content/index.md`:
-
-```md
----
-title: Welcome
----
-
-# Welcome
-
-This file renders at `/`.
+// ginko.config.ts
+docs: collection({
+  label: 'Docs',
+  source: 'files',
+  max: 500,
+  order: 'manual',
+  route: { en: '/docs/[slug]' },
+  fields: { title: f.text('Title'), slug: f.slug('Address', { from: 'title' }), body: f.markdown('Text') },
+}),
 ```
 
-Render the current route through the collection:
-
-```vue
-<!-- pages/[...slug].vue -->
-<script setup lang="ts">
-import { pages } from '~~/content.config'
-
-definePageMeta({ key: route => route.path })
-
-const { page } = await useContentPage(pages)
-
-if (!page.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
-}
-</script>
-
-<template>
-  <ContentRenderer v-if="page" :value="page" />
-</template>
+```text
+content/docs/1.getting-started.md      one entry; the number is the order
+content/docs/1.getting-started.de.md   its translation
 ```
 
-## Features
-
-- 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`, `navigation`,
-  and `surround`
-- route and search composables, plus one-shot async client query functions for other
-  reads
-- search helpers for MiniSearch, Pagefind, and provider-owned search
-- sitemap integration for public content routes
-- a server-side provider contract for advanced custom sources
-
-## I18n, Sitemap, and Prerender Ownership
-
-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 < 9` when translated static app slugs such as `/preise`
-and `/en/pricing` need cross-locale sitemap alternates.
-
-See the public guide:
-[Sitemap and prerender](https://github.com/lupinum-dev/ginko-content/blob/main/docs/content/docs/4.guides/9.sitemap-and-prerender.md).
-
-## Integration Dependencies
-
-| Feature | Dependency model |
-| --- | --- |
-| Markdown highlighting and built-in Shiki transformers | Included as runtime dependencies of `@lupinum/ginko-content`. |
-| Math Markdown | Install the optional `katex` peer and add `katex/dist/katex.min.css` to Nuxt's `css` array. |
-| Mermaid Markdown | Install the optional `beautiful-mermaid` peer. |
-| MiniSearch backend | Included as a runtime dependency and used by the default search backend. |
-| Pagefind backend | Install the optional `pagefind` peer when `content.search.engine` is `'pagefind'`. |
-| Provider-owned search | No extra package. The active content provider must advertise and implement `search`. |
-| Content i18n | Install and configure `@nuxtjs/i18n` 10.x when the app uses Nuxt locale routes. |
-| Sitemap XML output | Install and configure `@nuxtjs/sitemap`; Ginko contributes the content sitemap source. |
-
-Markdown plugins are opt-in. Omitting `content.markdown.plugins` is identical
-to `plugins: []`; add `shiki`, `math`, `mermaid`, `toc`, or `summary` only when
-the application needs that behavior.
-
-## 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.
-
-## Project links
+The Ginko Nuxt module finds this package by itself. It serves the Markdown of a page with the page,
+adds `<GinkoMarkdown>` and a search index. A file error fails the build and names the file.
 
-- Documentation source: [Getting started](https://github.com/lupinum-dev/ginko-content/blob/main/docs/content/docs/1.get-started/1.quickstart.md)
-- Repository: [github.com/lupinum-dev/ginko-content](https://github.com/lupinum-dev/ginko-content)
-- Issues: [GitHub issues](https://github.com/lupinum-dev/ginko-content/issues)
-- Contributing: [CONTRIBUTING.md](https://github.com/lupinum-dev/ginko-content/blob/main/CONTRIBUTING.md)
-- Security: [SECURITY.md](https://github.com/lupinum-dev/ginko-content/blob/main/SECURITY.md)
+Full guide: [Content from files](https://ginko-docs.vercel.app/en/docs/content-from-files).
 
-## Credits
+## Stability
 
-Ginko Content is an independently maintained fork derived from
-[Nuxt Content](https://content.nuxt.com/). It has substantially diverged while
-retaining upstream-derived parser, MDC, and rendering foundations. Credits also
-go to [Nuxt UI](https://ui.nuxt.com/) and [Comark](https://comark.dev/), the
-successor to the previous MDC work.
+You install this package; you do not import it. The Ginko module and `ginko check` load it. Its
+exports are the contract between the Ginko packages and can change in any release.
 
 ## License
 
-[MIT](./LICENSE)
+MIT © Lupinum OG

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+import { Locale, MarkdownValue, MarkdownTree } from '@lupinum/ginko';
+import { Schema, Bundle } from '@lupinum/ginko/internal';
+import { SearchIndexJson } from '@lupinum/ginko/search';
+
+interface ContentError {
+    /** Path relative to the content directory, e.g. `docs/1.einstieg.en.md`. */
+    file: string;
+    /** Field path as in validate() issues, when the error belongs to one field. */
+    path?: string;
+    message: string;
+    /** 1-based line in the file, when the error belongs to one (YAML, JSON and CSV parse errors, CSV rows). */
+    line?: number;
+}
+/**
+ * One error as `ginko check` and the build print it: `content/<file>:<line> (<field>): <message>`.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function errorLine(e: ContentError): string;
+interface ReadOptions {
+    /** `false` leaves out entries marked `draft: true`. Default `true` (dev shows drafts). */
+    drafts?: boolean;
+}
+
+/**
+ * The bundle for page state: every markdown tree replaced by `{ ref, toc }` (CONTENT.md, Phase 14).
+ * `trees` collects the trees by their ref, for the route that serves them.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function withMarkdownRefs(bundle: Bundle, schema: Schema, trees: Map<string, MarkdownValue>): Bundle;
+/**
+ * The bundle a site serves to everyone (`/__ginko/files/*`, page state, search): items whose visibility window
+ * ended before `now` are left out (an expired offer is not private data to publish), and the repo path
+ * `source` is dropped unless `keepSource` is set (docs pages need it for their "Edit this page" link).
+ * Items whose window is current or still to come stay: the page filters them by date in the browser.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function publicBundle(bundle: Bundle, schema: Schema, now: Date, options?: {
+    keepSource?: boolean;
+}): Bundle;
+/**
+ * One bundle per locale from the files, built by the core's buildBundle, so visibility, order, URLs
+ * and fallbacks follow the same rules as platform content. Revisions are 0: files have no history.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function buildFileBundles(options: BuildOptions): Promise<BuildResult>;
+interface BuildOptions extends ReadOptions {
+    /** The site's `content/` folder. */
+    contentDir: string;
+    /** The site's `public/` folder. */
+    publicDir: string;
+    schema: Schema;
+    /** The time the build counts as "now" (visibility windows, `generatedAt`). Default: the current time. */
+    now?: Date;
+    /** Where the WebP variants of the site's images are written (the folder served at `/_ginko/img`). Without it, no variants are made. */
+    imageDir?: string;
+}
+interface BuildResult {
+    /** One bundle per locale of the schema. */
+    bundles: Partial<Record<Locale, Bundle>>;
+    /** Co-located Markdown images: served URL to absolute path. */
+    images: Map<string, string>;
+    /** Every WebP variant file name that was written to `imageDir`. */
+    imageFiles: Set<string>;
+    errors: ContentError[];
+}
+
+/**
+ * The serialized search index of one locale's bundle (see searchSections). `bundle` must hold the `{ ref }`
+ * markdown values that withMarkdownRefs wrote, and `trees` the trees behind those refs.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function searchIndex(bundle: Bundle, trees: Map<string, MarkdownTree>, schema: Schema): Promise<SearchIndexJson>;
+
+export { buildFileBundles, errorLine, publicBundle, searchIndex, withMarkdownRefs };

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { Locale, MarkdownValue, MarkdownTree } from '@lupinum/ginko';
+import { Schema, Bundle } from '@lupinum/ginko/internal';
+import { SearchIndexJson } from '@lupinum/ginko/search';
+
+interface ContentError {
+    /** Path relative to the content directory, e.g. `docs/1.einstieg.en.md`. */
+    file: string;
+    /** Field path as in validate() issues, when the error belongs to one field. */
+    path?: string;
+    message: string;
+    /** 1-based line in the file, when the error belongs to one (YAML, JSON and CSV parse errors, CSV rows). */
+    line?: number;
+}
+/**
+ * One error as `ginko check` and the build print it: `content/<file>:<line> (<field>): <message>`.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function errorLine(e: ContentError): string;
+interface ReadOptions {
+    /** `false` leaves out entries marked `draft: true`. Default `true` (dev shows drafts). */
+    drafts?: boolean;
+}
+
+/**
+ * The bundle for page state: every markdown tree replaced by `{ ref, toc }` (CONTENT.md, Phase 14).
+ * `trees` collects the trees by their ref, for the route that serves them.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function withMarkdownRefs(bundle: Bundle, schema: Schema, trees: Map<string, MarkdownValue>): Bundle;
+/**
+ * The bundle a site serves to everyone (`/__ginko/files/*`, page state, search): items whose visibility window
+ * ended before `now` are left out (an expired offer is not private data to publish), and the repo path
+ * `source` is dropped unless `keepSource` is set (docs pages need it for their "Edit this page" link).
+ * Items whose window is current or still to come stay: the page filters them by date in the browser.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function publicBundle(bundle: Bundle, schema: Schema, now: Date, options?: {
+    keepSource?: boolean;
+}): Bundle;
+/**
+ * One bundle per locale from the files, built by the core's buildBundle, so visibility, order, URLs
+ * and fallbacks follow the same rules as platform content. Revisions are 0: files have no history.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function buildFileBundles(options: BuildOptions): Promise<BuildResult>;
+interface BuildOptions extends ReadOptions {
+    /** The site's `content/` folder. */
+    contentDir: string;
+    /** The site's `public/` folder. */
+    publicDir: string;
+    schema: Schema;
+    /** The time the build counts as "now" (visibility windows, `generatedAt`). Default: the current time. */
+    now?: Date;
+    /** Where the WebP variants of the site's images are written (the folder served at `/_ginko/img`). Without it, no variants are made. */
+    imageDir?: string;
+}
+interface BuildResult {
+    /** One bundle per locale of the schema. */
+    bundles: Partial<Record<Locale, Bundle>>;
+    /** Co-located Markdown images: served URL to absolute path. */
+    images: Map<string, string>;
+    /** Every WebP variant file name that was written to `imageDir`. */
+    imageFiles: Set<string>;
+    errors: ContentError[];
+}
+
+/**
+ * The serialized search index of one locale's bundle (see searchSections). `bundle` must hold the `{ ref }`
+ * markdown values that withMarkdownRefs wrote, and `trees` the trees behind those refs.
+ * @internal Loaded by the Ginko module and CLI; sites do not import it.
+ */
+declare function searchIndex(bundle: Bundle, trees: Map<string, MarkdownTree>, schema: Schema): Promise<SearchIndexJson>;
+
+export { buildFileBundles, errorLine, publicBundle, searchIndex, withMarkdownRefs };