@pitlane/content 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @pitlane/content
 
+## 0.2.2
+
+### Patch Changes
+
+- 6be8e56: Documentation only. No code changed.
+
+    - Every README now says where the documentation is published as Markdown for AI agents and other LLM tools: `https://pitlane.tools/llms.txt` indexes every page, `https://pitlane.tools/llms-full.txt` holds them all in one file, and any page URL with `.md` appended returns that page as Markdown.
+    - The `@pitlane/content` README gains the Vite setup the content guide describes. That setup covers the `satteri` and `vite-plugin-satteri` dev dependencies, and a `vite.config.ts` registering `satteri()` with `jsxImportSource: "remix/ui"`, `headings()`, `rawStyles()`, and `contentLayer()` before `remix()`. Before this, the README named `contentLayer()` but not the plugins it has to sit beside, and an MDX file compiled without `jsxImportSource: "remix/ui"` is a React component rather than a Remix one.
+    - The `@pitlane/content` entry-point table lists `@pitlane/content/hot`, and the README describes the four `@pitlane/content/internal/*` entry points as internal and unstable, with what each one is for: reuse by a plugin for a bundler other than Vite.
+
+- d4dfade: Documentation comments, plus two type-only exports from `@pitlane/content`. No runtime behavior changed.
+
+    - `@pitlane/content` now exports the `Content` and `ReferenceSchema` types. `Content<T>` is what `createContent()` returns, and `ReferenceSchema<C>` is what `c.reference(collection)` returns. Both already appeared in those signatures; now code can import them by name.
+    - The TSDoc that editors show and the reference at pitlane.tools is built from now covers more. `remix()` and `createContent()` have examples. The package entry points and the main functions link to their guides. `RemixPluginOptions`, `PrerenderConfig`, `PrerenderOption`, `CrawlOptions`, `D1DatabaseOptions`, `D1DriverOptions`, `D1Meta`, `D1PreparedStatement`, and `D1Result` have summaries. Every `@pitlane/content` entry point and the `@pitlane/theme/default` and `@pitlane/theme/dtcg` entry points have module summaries.
+    - `loaders.file()` describes the file shapes it accepts and when `options.parser` is required. `ThemeResult.extend()` describes what its patch may hold. `DefaultTheme` lists its top-level token groups.
+
+    `@pitlane/dev/assets` documents each `?assets` import form and `pitlane:dev`, and has its own reference page.
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -47,14 +47,63 @@ if (post) {
 
 The loaders are ordinary runtime code, which covers Node, Bun, Deno, and container hosts. For a host with no filesystem, add `contentLayer()` from `@pitlane/content/vite` and the build resolves the collections ahead of time, inlining entry data and compiling Markdown bodies into the bundle. The collection declarations do not change.
 
+## Configuring Vite
+
+With a Vite build, Markdown and MDX need two build-only dependencies. [`@pitlane/dev`](https://pitlane.tools/guides/vite-plugin) is assumed and installs the same way:
+
+```sh
+npm install --save-dev satteri vite-plugin-satteri
+```
+
+Register the Sätteri plugin and `contentLayer()` in your Vite config, before `remix()`:
+
+```ts
+// vite.config.ts
+import { headings, rawStyles } from "@pitlane/content/satteri";
+import { contentLayer } from "@pitlane/content/vite";
+import { remix } from "@pitlane/dev";
+import { defineConfig } from "vite";
+import satteri from "vite-plugin-satteri";
+
+export default defineConfig({
+    plugins: [
+        satteri({
+            mdx: { jsxImportSource: "remix/ui" },
+            mdastPlugins: [headings()],
+            hastPlugins: [rawStyles()],
+        }),
+        contentLayer(),
+        remix(),
+    ],
+});
+```
+
+`satteri()` compiles Markdown and MDX bodies during the build. `jsxImportSource: "remix/ui"` is required, because it is what makes a compiled MDX file a Remix component rather than a React one. `headings()` collects the heading list that `render()` returns, and `rawStyles()` keeps the CSS inside a `<style>` element intact, which any content with a highlighted code block produces.
+
+`contentLayer()` executes `app/content.ts` in Node during the build and inlines every collection's entries into the bundle, so a deployed application never reads the filesystem. Name a module at another path with `contentLayer({ entry: "app/collections.ts" })`. A collection of only JSON or YAML files needs `contentLayer()` alone, with none of the Sätteri setup.
+
+The [content guide](https://pitlane.tools/guides/content#configuring-vite) covers this setup in full.
+
 ## Entry points
 
-| Entry point                | Exports                                     |
-| -------------------------- | ------------------------------------------- |
-| `@pitlane/content`         | `createContent` and the collection types    |
-| `@pitlane/content/loaders` | `glob`, `file`                              |
-| `@pitlane/content/satteri` | `headings` and `rawStyles`, Sätteri plugins |
-| `@pitlane/content/vite`    | `contentLayer`, the build-time plugin       |
+| Entry point                | Exports                                                      |
+| -------------------------- | ------------------------------------------------------------ |
+| `@pitlane/content`         | `createContent` and the collection types                     |
+| `@pitlane/content/loaders` | `glob`, `file`                                               |
+| `@pitlane/content/satteri` | `headings` and `rawStyles`, Sätteri plugins                  |
+| `@pitlane/content/vite`    | `contentLayer`, the build-time plugin                        |
+| `@pitlane/content/hot`     | `hotContent`, which reloads the browser when content changes |
+
+`hotContent()` is for an application that runs from source with no build. It does nothing unless `remix/node-hmr` supervises the process, so it can stay in production code.
+
+### Internal entry points
+
+Four more entry points exist so that a plugin for a bundler other than Vite can reuse the pieces `contentLayer()` is built from. They are internal and unstable: they have no reference pages, and they can change in any release.
+
+- `@pitlane/content/internal/manifest` is the module a build plugin replaces with the collections it prebuilt. As published, it declares that nothing was prebuilt, so without a plugin every collection falls through to its loader.
+- `@pitlane/content/internal/prebuild` is the channel between the build plugin and `createContent()`. `openPrebuild()` and `closePrebuild()` bracket evaluating the content module, and the returned channel carries the collections, watched paths, and pending loads recorded in between.
+- `@pitlane/content/internal/codegen` writes the manifest module as JavaScript source with `manifestModule()`, and exports `BODY_PREFIX`, the prefix of the virtual modules that carry each entry's body.
+- `@pitlane/content/internal/mdx` exports `readEsm()`, which separates the imports in an MDX document's top-level ESM block from the rest of it.
 
 ## Without Remix
 
@@ -67,6 +116,8 @@ The loaders, schema validation, and query methods work with any [Standard Schema
 - [Custom loaders](https://pitlane.tools/guides/content#custom-loaders)
 - [API reference](https://pitlane.tools/package/content/)
 
+For AI agents and other LLM tools, the documentation is also published as Markdown. [`llms.txt`](https://pitlane.tools/llms.txt) indexes every page, [`llms-full.txt`](https://pitlane.tools/llms-full.txt) holds them all in one file, and every page has a Markdown twin at its URL plus `.md`, or plus `index.md` when the URL ends in `/`, such as [`https://pitlane.tools/guides/content.md`](https://pitlane.tools/guides/content.md).
+
 ## License
 
 MIT

package/dist/codegen.d.mts

@@ -1,4 +1,4 @@
-import { p as LoadedEntry } from "./types-xSR1WTBq.mjs";
+import { p as LoadedEntry } from "./types-C13GEJhr.mjs";
 //#region src/codegen.d.ts
 /** The prefix of the virtual modules that carry each entry's raw body. */
 declare const BODY_PREFIX = "\0pitlane-content/entry/";

package/dist/hot.d.mts

@@ -37,6 +37,8 @@ interface BrowserHmrChannel {
  * follow this module into a Worker bundle.
  *
  * @param content The object `createContent` returned.
+ *
+ * @see {@link https://pitlane.tools/guides/content-no-build | Content guide, without a build}
  */
 declare function hotContent(content: Record<string, unknown>): Promise<void>;
 /**

package/dist/hot.mjs

@@ -3,6 +3,15 @@ import { contentRoot } from "./prebuild.mjs";
 import * as path from "node:path";
 //#region src/hot.ts
 /**
+* Browser reloads during development when a file behind a collection
+* changes, for servers that `remix/node-hmr` supervises rather than Vite.
+* See {@link hotContent}.
+*
+* @see {@link https://pitlane.tools/guides/content-no-build | Content guide, without a build}
+*
+* @module
+*/
+/**
 * Reloads the browser when a file behind a collection changes.
 *
 * Call it once, beside `createContent`, and leave it in for production: it
@@ -13,6 +22,8 @@ import * as path from "node:path";
 * follow this module into a Worker bundle.
 *
 * @param content The object `createContent` returned.
+*
+* @see {@link https://pitlane.tools/guides/content-no-build | Content guide, without a build}
 */
 async function hotContent(content) {
 	if (!process.env.REMIX_NODE_HMR) return;

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { _ as Reference, a as ContentBuilder, c as EntryBody, d as LiveEntry, f as LiveLoader, h as LoaderContext, i as Content, l as GenerateIdOptions, m as Loader, n as CollectionDefinition, o as ContentLoader, p as LoadedEntry, r as CollectionEntry, s as Entry, t as Collection, u as Heading, v as RenderedEntry } from "./types-xSR1WTBq.mjs";
+import { _ as Reference, a as ContentBuilder, c as EntryBody, d as LiveEntry, f as LiveLoader, h as LoaderContext, i as Content, l as GenerateIdOptions, m as Loader, n as CollectionDefinition, o as ContentLoader, p as LoadedEntry, r as CollectionEntry, s as Entry, t as Collection, u as Heading, v as ReferenceSchema, y as RenderedEntry } from "./types-C13GEJhr.mjs";
 //#region src/content.d.ts
 /**
  * Declares a set of content collections.
@@ -8,7 +8,42 @@ import { _ as Reference, a as ContentBuilder, c as EntryBody, d as LiveEntry, f
  *
  * Under `contentLayer()`, registers deferred population work. The plugin
  * awaits it after evaluating the declarations and before emitting the bundle.
+ *
+ * @param build - Receives the {@link ContentBuilder} and returns one
+ * collection per key, each declared with `c.collection({ loader, schema })`
+ * @returns One {@link Collection} per key of the object `build` returned
+ * @throws Error when `c.reference()` names a collection `build` did not declare
+ *
+ * @see {@link https://pitlane.tools/guides/content | Content guide}
+ * @see {@link https://pitlane.tools/guides/content-no-build | Content guide, without a build}
+ *
+ * @example
+ * ```ts
+ * // app/content.ts
+ * import { createContent } from "@pitlane/content";
+ * import * as loaders from "@pitlane/content/loaders";
+ * import * as s from "remix/data-schema";
+ * import * as coerce from "remix/data-schema/coerce";
+ *
+ * export let content = createContent(c => ({
+ *     blog: c.collection({
+ *         loader: loaders.glob({ base: "app/content/blog", pattern: "*.{md,mdx}" }),
+ *         schema: s.object({
+ *             title: s.string(),
+ *             pubDate: coerce.date(),
+ *             author: c.reference("authors"),
+ *         }),
+ *     }),
+ *     authors: c.collection({
+ *         loader: loaders.file("app/content/authors.json"),
+ *         schema: s.object({ name: s.string() }),
+ *     }),
+ * }));
+ *
+ * let posts = await content.blog.getCollection();
+ * let post = await content.blog.getEntry("hello-world");
+ * ```
  */
 declare function createContent<T extends Record<string, CollectionDefinition>>(build: (c: ContentBuilder) => T): Content<T>;
 //#endregion
-export { type Collection, type CollectionDefinition, type CollectionEntry, type ContentBuilder, type ContentLoader, type Entry, type EntryBody, type GenerateIdOptions, type Heading, type LiveEntry, type LiveLoader, type LoadedEntry, type Loader, type LoaderContext, type Reference, type RenderedEntry, createContent };
+export { type Collection, type CollectionDefinition, type CollectionEntry, type Content, type ContentBuilder, type ContentLoader, type Entry, type EntryBody, type GenerateIdOptions, type Heading, type LiveEntry, type LiveLoader, type LoadedEntry, type Loader, type LoaderContext, type Reference, type ReferenceSchema, type RenderedEntry, createContent };

package/dist/index.mjs

@@ -126,6 +126,41 @@ function relativeTo(root, filePath) {
 *
 * Under `contentLayer()`, registers deferred population work. The plugin
 * awaits it after evaluating the declarations and before emitting the bundle.
+*
+* @param build - Receives the {@link ContentBuilder} and returns one
+* collection per key, each declared with `c.collection({ loader, schema })`
+* @returns One {@link Collection} per key of the object `build` returned
+* @throws Error when `c.reference()` names a collection `build` did not declare
+*
+* @see {@link https://pitlane.tools/guides/content | Content guide}
+* @see {@link https://pitlane.tools/guides/content-no-build | Content guide, without a build}
+*
+* @example
+* ```ts
+* // app/content.ts
+* import { createContent } from "@pitlane/content";
+* import * as loaders from "@pitlane/content/loaders";
+* import * as s from "remix/data-schema";
+* import * as coerce from "remix/data-schema/coerce";
+*
+* export let content = createContent(c => ({
+*     blog: c.collection({
+*         loader: loaders.glob({ base: "app/content/blog", pattern: "*.{md,mdx}" }),
+*         schema: s.object({
+*             title: s.string(),
+*             pubDate: coerce.date(),
+*             author: c.reference("authors"),
+*         }),
+*     }),
+*     authors: c.collection({
+*         loader: loaders.file("app/content/authors.json"),
+*         schema: s.object({ name: s.string() }),
+*     }),
+* }));
+*
+* let posts = await content.blog.getCollection();
+* let post = await content.blog.getEntry("hello-world");
+* ```
 */
 function createContent(build) {
 	let referenced = [];

package/dist/loaders.d.mts

@@ -1,4 +1,4 @@
-import { l as GenerateIdOptions, o as ContentLoader } from "./types-xSR1WTBq.mjs";
+import { l as GenerateIdOptions, o as ContentLoader } from "./types-C13GEJhr.mjs";
 import { CompileOptions } from "satteri";
 //#region src/loaders/file.d.ts
 /**
@@ -9,6 +9,8 @@ import { CompileOptions } from "satteri";
  * TOML reader — is typed as returning a JSON-value union, which a narrower
  * type rejects. `entriesOf` refuses an unusable result by name, so demanding
  * the caller narrow first would buy a wrapper and no safety.
+ *
+ * @inline
  */
 type Parser = (text: string) => unknown;
 /**
@@ -16,6 +18,13 @@ type Parser = (text: string) => unknown;
  *
  * Every entry is data rather than a document: a file of records has no body to
  * render, so `render()` on one of these entries is a mistake and says so.
+ *
+ * The file holds either an object whose keys are entry ids or an array of
+ * entries that each carry an `id`. `.json`, `.yaml`, and `.yml` parse without
+ * options; any other format needs `options.parser`, which turns the file's
+ * text into that object or array.
+ *
+ * @see {@link https://pitlane.tools/guides/content | Content guide}
  */
 declare function file(fileName: string, options?: {
   parser?: Parser;
@@ -27,6 +36,8 @@ declare function file(fileName: string, options?: {
  *
  * `pattern` is an ordinary runtime value — computed, read from the environment,
  * or assembled in a loop — because nothing about it is read statically.
+ *
+ * @see {@link https://pitlane.tools/guides/content | Content guide}
  */
 declare function glob(options: {
   pattern: string | string[];

package/dist/loaders.mjs

@@ -49,6 +49,13 @@ function read(parse, text, filePath) {
 *
 * Every entry is data rather than a document: a file of records has no body to
 * render, so `render()` on one of these entries is a mistake and says so.
+*
+* The file holds either an object whose keys are entry ids or an array of
+* entries that each carry an `id`. `.json`, `.yaml`, and `.yml` parse without
+* options; any other format needs `options.parser`, which turns the file's
+* text into that object or array.
+*
+* @see {@link https://pitlane.tools/guides/content | Content guide}
 */
 function file(fileName, options) {
 	let watched = [];
@@ -163,6 +170,8 @@ let formats = {
 *
 * `pattern` is an ordinary runtime value — computed, read from the environment,
 * or assembled in a loop — because nothing about it is read statically.
+*
+* @see {@link https://pitlane.tools/guides/content | Content guide}
 */
 function glob(options) {
 	let watched = [];

package/dist/prebuild.d.mts

@@ -1,4 +1,4 @@
-import { g as PrebuiltCollections } from "./types-xSR1WTBq.mjs";
+import { g as PrebuiltCollections } from "./types-C13GEJhr.mjs";
 //#region src/prebuild.d.ts
 /**
  * The channel between `contentLayer()` and `createContent`.

package/dist/{types-xSR1WTBq.d.mts → types-C13GEJhr.d.mts}

@@ -83,7 +83,14 @@ interface ChainableSchema<Input, Output> {
   refine: (predicate: (value: Output) => boolean, message?: string) => ChainableSchema<Input, Output>;
   transform: <Next>(transformer: (value: Output) => Next) => ChainableSchema<Input, Next>;
 }
-/** The schema `c.reference(collection)` returns. */
+/**
+ * The schema `c.reference(collection)` returns: a Standard Schema that reads
+ * an entry id (a string) and outputs a {@link Reference} into `collection`.
+ *
+ * It composes inside `remix/data-schema`'s `s.object`, `s.array`, and
+ * `s.optional` like any other schema. It does not check that the target entry
+ * exists; a dangling id surfaces as `getEntry` resolving to `undefined`.
+ */
 type ReferenceSchema<C extends string> = ChainableSchema<string, Reference<C>>;
 /** A heading collected from a Markdown or MDX document. */
 interface Heading {
@@ -200,7 +207,11 @@ interface ContentBuilder {
   }): CollectionDefinition<S>;
   reference<C extends string>(collection: C): ReferenceSchema<C>;
 }
-/** The object `createContent` returns: one {@link Collection} per key. */
+/**
+ * The object `createContent` returns: one {@link Collection} per key of the
+ * definitions its callback returned, named after that key and typed by the
+ * output of that collection's schema.
+ */
 type Content<T extends Record<string, CollectionDefinition>> = { [K in keyof T]: Collection<K & string, InferSchema<T[K]["schema"]>>; };
 /** How `contentLayer()` spells an entry's body in the manifest it emits. */
 type PrebuiltBody = {
@@ -235,4 +246,4 @@ interface GenerateIdOptions {
   data: Record<string, unknown>;
 }
 //#endregion
-export { Reference as _, ContentBuilder as a, EntryBody as c, LiveEntry as d, LiveLoader as f, PrebuiltCollections as g, LoaderContext as h, Content as i, GenerateIdOptions as l, Loader as m, CollectionDefinition as n, ContentLoader as o, LoadedEntry as p, CollectionEntry as r, Entry as s, Collection as t, Heading as u, RenderedEntry as v };
+export { Reference as _, ContentBuilder as a, EntryBody as c, LiveEntry as d, LiveLoader as f, PrebuiltCollections as g, LoaderContext as h, Content as i, GenerateIdOptions as l, Loader as m, CollectionDefinition as n, ContentLoader as o, LoadedEntry as p, CollectionEntry as r, Entry as s, Collection as t, Heading as u, ReferenceSchema as v, RenderedEntry as y };

package/dist/vite.d.mts

@@ -10,6 +10,8 @@ import { Plugin } from "vite";
  *
  * The result is a host with no filesystem serving the collections the
  * application declared, with no change to the declarations.
+ *
+ * @see {@link https://pitlane.tools/guides/content | Content guide}
  */
 declare function contentLayer(options?: {
   entry?: string;

package/dist/vite.mjs

@@ -4,6 +4,15 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRunnableDevEnvironment, createServer } from "vite";
 //#region src/vite.ts
+/**
+* The {@link contentLayer} Vite plugin, which resolves every collection
+* during the build and inlines the entries into the bundle, so a host with no
+* filesystem serves the same collections.
+*
+* @see {@link https://pitlane.tools/guides/content | Content guide}
+*
+* @module
+*/
 const MANIFEST_OWNER = "@pitlane/content";
 const MANIFEST_SPECIFIER = `${MANIFEST_OWNER}/internal/manifest`;
 const VIRTUAL_MANIFEST = "\0pitlane-content/manifest";
@@ -17,6 +26,8 @@ const VIRTUAL_MANIFEST = "\0pitlane-content/manifest";
 *
 * The result is a host with no filesystem serving the collections the
 * application declared, with no change to the declarations.
+*
+* @see {@link https://pitlane.tools/guides/content | Content guide}
 */
 function contentLayer(options) {
 	let entry = options?.entry ?? "app/content.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitlane/content",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Schema-validated content collections for Remix.",
   "keywords": [
     "content",