@foldkit/markdown 0.2.0 → 0.3.0

package/README.md

@@ -54,6 +54,8 @@ const view = (h: HtmlBuilder<Message>): Html =>
   h.div([], [Markdown.view(about)])
 ```
 
+`decodeDocument` memoizes on the wire object, so calling it inside a view decodes each module once rather than once per render.
+
 `Markdown.view` renders every node through unstyled semantic defaults. Restyle any node by overriding its view:
 
 ```typescript
@@ -144,11 +146,54 @@ const postView = (
 
 Attribute values are strings on the wire, so transforming field schemas decode past them: `S.NumberFromString` turns `::Chart{height="240"}` into `height: number`. A plain `islands` record of untyped views (`Readonly<Record<string, IslandView>>`) also works when you want to skip the schemas.
 
+## Frontmatter
+
+Documents can open with a frontmatter block when the plugin is given a schema for it. Declare the fields as a Schema struct, once, in a module both your Vite config and your application import:
+
+```typescript
+// src/postFrontmatter.ts
+import { Schema as S } from 'effect'
+
+export const PostFrontmatter = S.Struct({
+  title: S.String.check(S.isNonEmpty()),
+  date: S.String,
+})
+```
+
+```typescript
+import { markdown } from '@foldkit/markdown/vite'
+
+import { PostFrontmatter } from './src/postFrontmatter'
+
+markdown({ frontmatter: PostFrontmatter })
+```
+
+```markdown
+---
+title: 'Introducing the blog'
+date: 2026-08-01
+---
+
+The prose starts here.
+```
+
+Every field validates at build time. An unknown field, a missing required field, or a value the schema rejects fails the build with the file and line. Without a `frontmatter` schema, a frontmatter block fails the build.
+
+The supported shape is deliberately flat: one `key: value` pair per line, every value a string. A value wrapped in matching single or double quotes has that outer pair stripped, so values containing special characters like `:` stay unambiguous. Only the first and last characters decide, so a value that itself starts and ends with the same quote character loses that pair; wrap it in the other quote style to keep it. Nesting, lists, and multi-line values are not supported.
+
+Every compiled `.md` module carries a `frontmatter` named export alongside the default document export. It holds the block's validated fields, and it is `undefined` when the document has no block:
+
+```typescript
+import postRaw, { frontmatter } from './post/introducing-the-blog.md'
+```
+
+The fields arrive as the raw strings the block declares. The build validates them against the schema and discards the decoded result, so where the application needs typed values, decode the export with the same schema at runtime; validation at build time means that decode cannot fail. `S.NumberFromString` and friends do their transformation in that runtime decode, not in the emitted module.
+
 ## Vocabulary
 
 The schema accepts CommonMark plus GFM tables and strikethrough: headings, paragraphs, emphasis, strong, strikethrough, inline code, links, images, hard breaks, nested lists, code blocks, blockquotes, thematic breaks, and tables. Directives (`::Name`, `:::Name`) become Island nodes.
 
-Anything outside the vocabulary fails the build with an error naming the construct and its line. Raw HTML is rejected by design; islands are the escape hatch. Reference-style links, footnotes, task lists, YAML frontmatter, and directive labels (`::Name[label]`) are not supported; keep document metadata in application code. Link and image URLs must be relative or use the `http:`, `https:`, `mailto:`, or `tel:` schemes; executable schemes like `javascript:` fail the build.
+Anything outside the vocabulary fails the build with an error naming the construct and its line. Raw HTML is rejected by design; islands are the escape hatch. Reference-style links, footnotes, task lists, and directive labels (`::Name[label]`) are not supported. Frontmatter is supported only with a `frontmatter` schema configured, in the flat shape described above. Link and image URLs must be relative or use the `http:`, `https:`, `mailto:`, or `tel:` schemes; executable schemes like `javascript:` fail the build.
 
 ## One-off compilation
 
@@ -161,3 +206,15 @@ import { islandAttributes } from './islands'
 
 const document = parseMarkdown('# Title', { islands: islandAttributes })
 ```
+
+`parseMarkdownWithFrontmatter` also returns the document's frontmatter fields, as an `Option` of the raw string record:
+
+```typescript
+import { parseMarkdownWithFrontmatter } from '@foldkit/markdown/vite'
+
+import { PostFrontmatter } from './postFrontmatter'
+
+const { document, maybeFrontmatter } = parseMarkdownWithFrontmatter(source, {
+  frontmatter: PostFrontmatter,
+})
+```

package/content.d.ts

@@ -1,4 +1,5 @@
 declare module '*.md' {
   const document: unknown
   export default document
+  export const frontmatter: unknown
 }

package/dist/ast/ast.d.ts

@@ -1,5 +1,5 @@
 import { Option, Schema as S } from 'effect';
-import type { Array } from 'effect';
+import type { Array, SchemaAST } from 'effect';
 /** Plain text. */
 export type Text = Readonly<{
     _tag: 'Text';
@@ -309,14 +309,23 @@ export type MarkdownDocumentEncoded = typeof MarkdownDocument.Encoded;
 /**
  * Decodes the default export of a compiled markdown module into a typed
  * {@link MarkdownDocument}. Throws on input outside the markdown vocabulary.
+ *
+ * Results are memoized on a `WeakMap` keyed by the wire object, so decoding the
+ * same compiled module again returns the document from the first decode. A
+ * module's wire object is immutable build output and the decode is
+ * deterministic, so a cached document can never disagree with a fresh one, and
+ * each entry is collected along with the module holding its key. Calling this
+ * from a view costs one decode per module rather than one per render.
+ *
+ * Passing `overrideOptions` bypasses the cache both ways: the decode ignores
+ * cached entries and its result is not stored, since a document decoded under
+ * one set of options cannot answer for another.
  */
-export declare const decodeDocument: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
-    readonly blocks: readonly Block[];
-};
+export declare const decodeDocument: (wire: unknown, overrideOptions?: SchemaAST.ParseOptions) => MarkdownDocument;
 /** Encodes a {@link MarkdownDocument} into its JSON-safe wire form. */
 export declare const encodeDocument: (input: {
     readonly blocks: readonly Block[];
-}, options?: import("effect/SchemaAST").ParseOptions) => {
+}, options?: SchemaAST.ParseOptions) => {
     readonly blocks: readonly BlockEncoded[];
 };
 //# sourceMappingURL=ast.d.ts.map

package/dist/ast/ast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/ast/ast.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/ast/ast.ts"],"names":[],"mappings":"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"}

package/dist/ast/ast.js

@@ -1,4 +1,4 @@
-import { Schema as S } from 'effect';
+import { Function, Option, Predicate, Schema as S } from 'effect';
 import { ts } from 'foldkit/schema';
 /** Schema for {@link Text}. */
 export const Text = ts('Text', { value: S.String });
@@ -107,10 +107,37 @@ export const Island = ts('Island', {
 // DOCUMENT
 /** A compiled markdown document: the block sequence of one source file. */
 export const MarkdownDocument = S.Struct({ blocks: S.Array(Block) });
+const decodeDocumentUncached = S.decodeUnknownSync(MarkdownDocument);
+const documentByWire = new WeakMap();
 /**
  * Decodes the default export of a compiled markdown module into a typed
  * {@link MarkdownDocument}. Throws on input outside the markdown vocabulary.
+ *
+ * Results are memoized on a `WeakMap` keyed by the wire object, so decoding the
+ * same compiled module again returns the document from the first decode. A
+ * module's wire object is immutable build output and the decode is
+ * deterministic, so a cached document can never disagree with a fresh one, and
+ * each entry is collected along with the module holding its key. Calling this
+ * from a view costs one decode per module rather than one per render.
+ *
+ * Passing `overrideOptions` bypasses the cache both ways: the decode ignores
+ * cached entries and its result is not stored, since a document decoded under
+ * one set of options cannot answer for another.
  */
-export const decodeDocument = S.decodeUnknownSync(MarkdownDocument);
+export const decodeDocument = (wire, overrideOptions) => {
+    if (overrideOptions === undefined && Predicate.isObject(wire)) {
+        return Option.match(Option.fromNullishOr(documentByWire.get(wire)), {
+            onNone: () => {
+                const document = decodeDocumentUncached(wire);
+                documentByWire.set(wire, document);
+                return document;
+            },
+            onSome: Function.identity,
+        });
+    }
+    else {
+        return decodeDocumentUncached(wire, overrideOptions);
+    }
+};
 /** Encodes a {@link MarkdownDocument} into its JSON-safe wire form. */
 export const encodeDocument = S.encodeSync(MarkdownDocument);

package/dist/vite/frontmatter.d.ts

@@ -0,0 +1,32 @@
+import type { Position } from 'unist';
+import type { FieldsSchema } from './validateFields.js';
+/**
+ * Schema for a document's frontmatter: a struct that validates the flat string
+ * fields at build time. Values stay the raw strings the block declares; where
+ * an app needs typed values, decode the exported `frontmatter` object with the
+ * same schema at runtime.
+ */
+export type FrontmatterDefinition = FieldsSchema;
+/**
+ * A frontmatter block's parsed string fields, alongside each field's line
+ * offset within the block so validation errors can point at the offending
+ * line rather than the opening fence.
+ */
+export type ParsedFrontmatterFields = Readonly<{
+    fields: Readonly<Record<string, string>>;
+    fieldLineOffsets: ReadonlyMap<string, number>;
+}>;
+/**
+ * Parses a frontmatter block's raw text into its string fields. The supported
+ * shape is deliberately flat: one `key: value` pair per line, every value a
+ * string, with optional surrounding quotes for values that contain special
+ * characters. Nesting, lists, and multi-line values all fail with guidance.
+ */
+export declare const parseFrontmatterFields: (value: string, maybePosition: Position | undefined) => ParsedFrontmatterFields;
+/**
+ * Validates parsed frontmatter fields against the plugin's frontmatter schema.
+ * Unknown fields and values outside the schema both fail with an error naming
+ * the offender and its line, mirroring how island attributes are validated.
+ */
+export declare const validateFrontmatterFields: (definition: FrontmatterDefinition, parsed: ParsedFrontmatterFields, maybePosition: Position | undefined) => void;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/vite/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/vite/frontmatter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAErC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAKvD;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,YAAY,CAAA;AAwBhD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACxC,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9C,CAAC,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,MAAM,EACb,eAAe,QAAQ,GAAG,SAAS,KAClC,uBAuCF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACpC,YAAY,qBAAqB,EACjC,QAAQ,uBAAuB,EAC/B,eAAe,QAAQ,GAAG,SAAS,KAClC,IAoBF,CAAA"}

package/dist/vite/frontmatter.js

@@ -0,0 +1,72 @@
+import { Array, Option, String as String_, pipe } from 'effect';
+import { validateFields } from './validateFields.js';
+const FRONTMATTER_ENTRY_PATTERN = /^([A-Za-z][A-Za-z0-9_-]*):(.*)$/;
+const sourceLocation = (maybePosition, lineOffset) => {
+    const startLine = maybePosition?.start.line;
+    if (startLine === undefined) {
+        return '';
+    }
+    else {
+        return ` (line ${startLine + lineOffset})`;
+    }
+};
+const isWrappedIn = (value, quote) => value.length >= 2 && value.startsWith(quote) && value.endsWith(quote);
+const unquote = (value) => isWrappedIn(value, '"') || isWrappedIn(value, "'")
+    ? value.slice(1, -1)
+    : value;
+/**
+ * Parses a frontmatter block's raw text into its string fields. The supported
+ * shape is deliberately flat: one `key: value` pair per line, every value a
+ * string, with optional surrounding quotes for values that contain special
+ * characters. Nesting, lists, and multi-line values all fail with guidance.
+ */
+export const parseFrontmatterFields = (value, maybePosition) => {
+    // NOTE: collected in a Map so field names inherited from Object.prototype
+    // (`toString`, `constructor`) neither trip the duplicate check nor land
+    // anywhere but an own property of the returned record.
+    const fieldValues = new Map();
+    const fieldLineOffsets = new Map();
+    const entryLines = pipe(String_.split(value, '\n'), Array.map((line, lineIndex) => ({ line, lineIndex })), Array.filter(({ line }) => String_.isNonEmpty(line.trim())));
+    for (const { line, lineIndex } of entryLines) {
+        const location = sourceLocation(maybePosition, lineIndex + 1);
+        const [fieldName, rawFieldValue] = Option.match(String_.match(FRONTMATTER_ENTRY_PATTERN)(line), {
+            onNone: () => {
+                throw new Error(`Invalid frontmatter entry${location}. ` +
+                    'Frontmatter supports flat `key: value` pairs of strings only. ' +
+                    'Nesting, lists, and multi-line values are not supported.');
+            },
+            onSome: ([, name = '', fieldValue = '']) => [
+                name,
+                fieldValue,
+            ],
+        });
+        if (fieldValues.has(fieldName)) {
+            throw new Error(`Duplicate frontmatter field "${fieldName}"${location}.`);
+        }
+        fieldValues.set(fieldName, unquote(rawFieldValue.trim()));
+        fieldLineOffsets.set(fieldName, lineIndex + 1);
+    }
+    return { fields: Object.fromEntries(fieldValues), fieldLineOffsets };
+};
+/**
+ * Validates parsed frontmatter fields against the plugin's frontmatter schema.
+ * Unknown fields and values outside the schema both fail with an error naming
+ * the offender and its line, mirroring how island attributes are validated.
+ */
+export const validateFrontmatterFields = (definition, parsed, maybePosition) => {
+    const fieldLocation = (fieldName) => Option.match(Option.fromNullishOr(parsed.fieldLineOffsets.get(fieldName)), {
+        onNone: () => sourceLocation(maybePosition, 0),
+        onSome: lineOffset => sourceLocation(maybePosition, lineOffset),
+    });
+    validateFields({
+        schema: definition,
+        values: parsed.fields,
+        memberNounPlural: 'fields',
+        unknownField: (fieldName, allowedDescription) => `Unknown frontmatter field "${fieldName}"${fieldLocation(fieldName)}. ` +
+            allowedDescription,
+        invalidValues: (detail, maybeFieldName) => `Invalid frontmatter${Option.match(maybeFieldName, {
+            onNone: () => sourceLocation(maybePosition, 0),
+            onSome: fieldLocation,
+        })}. ${detail}`,
+    });
+};

package/dist/vite/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/vite/normalize.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAKV,IAAI,EAEL,MAAM,OAAO,CAAA;AAId,OAAO,EAeL,gBAAgB,EASjB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAE7E;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,OAAO,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CACxC,CAAC,CAAA;AAoIF;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,IAAI,EACV,UAAS,gBAAqB,KAC7B,gBAwHF,CAAA"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/vite/normalize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAKV,IAAI,EAEL,MAAM,OAAO,CAAA;AAId,OAAO,EAeL,gBAAgB,EASjB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAG7E;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,OAAO,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CACxC,CAAC,CAAA;AAoIF;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,IAAI,EACV,UAAS,gBAAqB,KAC7B,gBA0GF,CAAA"}

package/dist/vite/normalize.js

@@ -1,5 +1,6 @@
-import { Array, Match as M, Option, Record as Record_, Schema as S, } from 'effect';
+import { Array, Match as M, Option, Record as Record_ } from 'effect';
 import { Blockquote, CodeBlock, Emphasis, HardBreak, Heading, Image, InlineCode, Island, Link, List, ListItem, Paragraph, Strikethrough, Strong, Table, TableCell, TableRow, Text, ThematicBreak, } from '../ast/index.js';
+import { validateFields } from './validateFields.js';
 const UNSUPPORTED_GUIDANCE = {
     html: 'Raw HTML is not part of the markdown vocabulary. Use an island directive to render custom views.',
     textDirective: 'Inline directives are not supported. Use a leaf directive (`::Name`) on its own line, or a container directive (`:::Name`).',
@@ -8,7 +9,7 @@ const UNSUPPORTED_GUIDANCE = {
     definition: 'Reference-style link definitions are not supported. Use inline links (`[text](url)`).',
     footnoteReference: 'Footnotes are not supported.',
     footnoteDefinition: 'Footnotes are not supported.',
-    yaml: 'Frontmatter is not supported. Keep document metadata in application code, for example a typed post registry.',
+    yaml: 'Frontmatter is not supported without a `frontmatter` schema in the markdown plugin options. Pass one to enable it, or keep document metadata in application code.',
     'leaf directive label': 'Leaf directive labels (`::Name[label]`) are not supported. Pass information through attributes (`::Name{label="..."}`) instead.',
 };
 const sourceLocation = (node) => {
@@ -70,25 +71,14 @@ const toTableRow = (row) => TableRow({
  * Throws on any node outside the markdown vocabulary.
  */
 export const normalizeRoot = (root, options = {}) => {
-    const validateIslandAttributes = (directive, attributesSchema, attributes) => {
-        const allowedAttributeNames = Object.keys(attributesSchema.fields);
-        const unknownAttributeNames = Object.keys(attributes).filter(attributeName => !allowedAttributeNames.includes(attributeName));
-        if (Array.isArrayNonEmpty(unknownAttributeNames)) {
-            const allowedDescription = Array.match(allowedAttributeNames, {
-                onEmpty: () => 'It takes no attributes.',
-                onNonEmpty: names => `Allowed attributes: ${names.join(', ')}.`,
-            });
-            throw new Error(`Unknown attribute "${Array.headNonEmpty(unknownAttributeNames)}" for island "${directive.name}"${sourceLocation(directive)}. ` +
-                allowedDescription);
-        }
-        try {
-            S.decodeUnknownSync(attributesSchema)(attributes);
-        }
-        catch (error) {
-            throw new Error(`Invalid attributes for island "${directive.name}"${sourceLocation(directive)}. ` +
-                `${error instanceof Error ? error.message : String(error)}`);
-        }
-    };
+    const validateIslandAttributes = (directive, attributesSchema, attributes) => validateFields({
+        schema: attributesSchema,
+        values: attributes,
+        memberNounPlural: 'attributes',
+        unknownField: (attributeName, allowedDescription) => `Unknown attribute "${attributeName}" for island "${directive.name}"${sourceLocation(directive)}. ` +
+            allowedDescription,
+        invalidValues: detail => `Invalid attributes for island "${directive.name}"${sourceLocation(directive)}. ${detail}`,
+    });
     const toIsland = (directive, blocks) => {
         const attributes = normalizeAttributes(directive.attributes);
         const { islands } = options;

package/dist/vite/public.d.ts

@@ -1,3 +1,4 @@
-export { markdown, parseMarkdown } from './vite.js';
-export type { MarkdownPluginOptions } from './vite.js';
+export { markdown, parseMarkdown, parseMarkdownWithFrontmatter, } from './vite.js';
+export type { MarkdownPluginOptions, ParsedMarkdown } from './vite.js';
+export type { FrontmatterDefinition } from './frontmatter.js';
 //# sourceMappingURL=public.d.ts.map

package/dist/vite/public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/vite/public.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACnD,YAAY,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/vite/public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,aAAa,EACb,4BAA4B,GAC7B,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AACtE,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/vite/public.js

@@ -1 +1 @@
-export { markdown, parseMarkdown } from './vite.js';
+export { markdown, parseMarkdown, parseMarkdownWithFrontmatter, } from './vite.js';

package/dist/vite/validateFields.d.ts

@@ -0,0 +1,25 @@
+import { Option, Schema as S } from 'effect';
+/**
+ * A struct schema describing a flat record of string values, the shape shared
+ * by island attribute definitions and frontmatter definitions.
+ */
+export type FieldsSchema = S.Struct<S.Struct.Fields> & Readonly<{
+    DecodingServices: never;
+    EncodingServices: never;
+}>;
+/**
+ * Validates a parsed string record against its schema: names outside the
+ * schema and values the schema rejects both fail with an error the caller
+ * phrases, and a rejected value's message also receives the failing field's
+ * name when the schema issue carries one. One implementation serves island
+ * attributes and frontmatter fields, so unknown-name detection and
+ * decode-error wrapping cannot drift between the two.
+ */
+export declare const validateFields: (config: Readonly<{
+    schema: FieldsSchema;
+    values: Readonly<Record<string, string>>;
+    memberNounPlural: string;
+    unknownField: (fieldName: string, allowedDescription: string) => string;
+    invalidValues: (detail: string, maybeFieldName: Option.Option<string>) => string;
+}>) => void;
+//# sourceMappingURL=validateFields.d.ts.map

package/dist/vite/validateFields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateFields.d.ts","sourceRoot":"","sources":["../../src/vite/validateFields.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EAEN,MAAM,IAAI,CAAC,EAGZ,MAAM,QAAQ,CAAA;AAIf;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAClD,QAAQ,CAAC;IAAE,gBAAgB,EAAE,KAAK,CAAC;IAAC,gBAAgB,EAAE,KAAK,CAAA;CAAE,CAAC,CAAA;AAoBhE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,QAAQ,CAAC;IACf,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACxC,gBAAgB,EAAE,MAAM,CAAA;IACxB,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,KAAK,MAAM,CAAA;IACvE,aAAa,EAAE,CACb,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAClC,MAAM,CAAA;CACZ,CAAC,KACD,IA6BF,CAAA"}

package/dist/vite/validateFields.js

@@ -0,0 +1,31 @@
+import { Array, Option, Predicate, Schema as S, SchemaIssue, pipe, } from 'effect';
+const maybeInvalidFieldName = (error) => pipe(error, Option.liftPredicate(S.isSchemaError), Option.map(schemaError => schemaError.issue), Option.flatMap(issue => issue instanceof SchemaIssue.Composite
+    ? Array.head(issue.issues)
+    : Option.some(issue)), Option.flatMap(issue => issue instanceof SchemaIssue.Pointer
+    ? Array.head(issue.path)
+    : Option.none()), Option.filter(Predicate.isString));
+/**
+ * Validates a parsed string record against its schema: names outside the
+ * schema and values the schema rejects both fail with an error the caller
+ * phrases, and a rejected value's message also receives the failing field's
+ * name when the schema issue carries one. One implementation serves island
+ * attributes and frontmatter fields, so unknown-name detection and
+ * decode-error wrapping cannot drift between the two.
+ */
+export const validateFields = (config) => {
+    const allowedFieldNames = Object.keys(config.schema.fields);
+    const unknownFieldNames = Object.keys(config.values).filter(fieldName => !allowedFieldNames.includes(fieldName));
+    if (Array.isArrayNonEmpty(unknownFieldNames)) {
+        const allowedDescription = Array.match(allowedFieldNames, {
+            onEmpty: () => `It takes no ${config.memberNounPlural}.`,
+            onNonEmpty: names => `Allowed ${config.memberNounPlural}: ${names.join(', ')}.`,
+        });
+        throw new Error(config.unknownField(Array.headNonEmpty(unknownFieldNames), allowedDescription));
+    }
+    try {
+        S.decodeUnknownSync(config.schema)(config.values);
+    }
+    catch (error) {
+        throw new Error(config.invalidValues(error instanceof Error ? error.message : String(error), maybeInvalidFieldName(error)));
+    }
+};

package/dist/vite/vite.d.ts

@@ -1,19 +1,41 @@
+import { Option } from 'effect';
 import type { Plugin } from 'vite';
 import { MarkdownDocument } from '../ast/index.js';
+import type { FrontmatterDefinition } from './frontmatter.js';
 import type { NormalizeOptions } from './normalize.js';
-/** Options for {@link markdown} and {@link parseMarkdown}. */
-export type MarkdownPluginOptions = NormalizeOptions;
+/** Options for {@link markdown}, {@link parseMarkdown}, and {@link parseMarkdownWithFrontmatter}. */
+export type MarkdownPluginOptions = NormalizeOptions & Readonly<{
+    frontmatter?: FrontmatterDefinition | undefined;
+}>;
+/** A parsed document together with its frontmatter fields, when it has any. */
+export type ParsedMarkdown = Readonly<{
+    document: MarkdownDocument;
+    maybeFrontmatter: Option.Option<Readonly<Record<string, string>>>;
+}>;
 /**
  * Parses markdown source into a typed {@link MarkdownDocument}. Throws on any
  * construct outside the markdown vocabulary, and on malformed options. The
  * {@link markdown} plugin runs this per `.md` module; call it directly for
- * one-off compilation in scripts.
+ * one-off compilation in scripts. Frontmatter, when enabled via the
+ * `frontmatter` option, is validated and dropped; use
+ * {@link parseMarkdownWithFrontmatter} to read it.
  */
 export declare const parseMarkdown: (source: string, options?: MarkdownPluginOptions) => MarkdownDocument;
+/**
+ * Like {@link parseMarkdown}, but also returns the document's frontmatter
+ * fields when the `frontmatter` option is set and the source carries a
+ * frontmatter block. The fields arrive as the raw strings the block declares,
+ * already validated against the schema, so decoding them with the same schema
+ * cannot fail.
+ */
+export declare const parseMarkdownWithFrontmatter: (source: string, options?: MarkdownPluginOptions) => ParsedMarkdown;
 /**
  * Vite plugin that compiles imported `.md` files at build time into typed
  * document modules. Decode the default export with `decodeDocument` and
- * render it with `Markdown.view`.
+ * render it with `Markdown.view`. Every module also carries a `frontmatter`
+ * named export: with a `frontmatter` schema configured, it holds the
+ * document's validated frontmatter fields, and it is `undefined` when the
+ * document has no frontmatter block.
  */
 export declare const markdown: (options?: MarkdownPluginOptions) => Plugin;
 //# sourceMappingURL=vite.d.ts.map

package/dist/vite/vite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../../src/vite/vite.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,EAAE,gBAAgB,EAAkB,MAAM,iBAAiB,CAAA;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAYtD,8DAA8D;AAC9D,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,CAAA;AAwBpD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,MAAM,EACd,UAAS,qBAA0B,KAClC,gBACwE,CAAA;AAE3E;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,UAAS,qBAA0B,KAAG,MAgB9D,CAAA"}
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../../src/vite/vite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAqB,MAAM,QAAQ,CAAA;AAOzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,EAAE,gBAAgB,EAAkB,MAAM,iBAAiB,CAAA;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAM7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AActD,qGAAqG;AACrG,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAClD,QAAQ,CAAC;IACP,WAAW,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAA;CAChD,CAAC,CAAA;AA0BJ,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;CAClE,CAAC,CAAA;AAwDF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,MAAM,EACd,UAAS,qBAA0B,KAClC,gBAEU,CAAA;AAEb;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GACvC,QAAQ,MAAM,EACd,UAAS,qBAA0B,KAClC,cACwE,CAAA;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,UAAS,qBAA0B,KAAG,MA2B9D,CAAA"}

package/dist/vite/vite.js

@@ -1,44 +1,90 @@
-import { Schema as S } from 'effect';
+import { Array, Option, Schema as S, pipe } from 'effect';
 import remarkDirective from 'remark-directive';
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
 import { encodeDocument } from '../ast/index.js';
+import { parseFrontmatterFields, validateFrontmatterFields, } from './frontmatter.js';
 import { normalizeRoot } from './normalize.js';
 // NOTE: remark-frontmatter is included so that YAML frontmatter parses as one
-// `yaml` node and fails the build with guidance. Without it, remark reads
-// `---` fences as a thematic break plus a setext heading and renders garbage.
+// `yaml` node. With a `frontmatter` schema configured it becomes the document's
+// typed frontmatter; without one it fails the build with guidance. Without the
+// remark plugin, remark reads `---` fences as a thematic break plus a setext
+// heading and renders garbage.
 const processor = unified()
     .use(remarkParse)
     .use(remarkFrontmatter)
     .use(remarkGfm)
     .use(remarkDirective)
     .freeze();
+const isSchemaStruct = (value) => S.isSchema(value) && 'fields' in value;
 const validateMarkdownPluginOptions = (options) => {
-    const islands = options.islands;
-    if (islands === undefined) {
-        return options;
-    }
-    for (const [islandName, attributesSchema] of Object.entries(islands)) {
-        if (!S.isSchema(attributesSchema) || !('fields' in attributesSchema)) {
-            throw new Error(`Island "${islandName}" in markdown plugin options must map to a Schema struct describing its attributes.`);
+    const { islands, frontmatter } = options;
+    if (islands !== undefined) {
+        for (const [islandName, attributesSchema] of Object.entries(islands)) {
+            if (!isSchemaStruct(attributesSchema)) {
+                throw new Error(`Island "${islandName}" in markdown plugin options must map to a Schema struct describing its attributes.`);
+            }
         }
     }
+    if (frontmatter !== undefined && !isSchemaStruct(frontmatter)) {
+        throw new Error('The `frontmatter` markdown plugin option must be a Schema struct describing the frontmatter fields.');
+    }
     return options;
 };
-const parseWithValidatedOptions = (source, options) => normalizeRoot(processor.parse(source), options);
+const isYamlNode = (node) => node.type === 'yaml';
+const extractFrontmatter = (root, frontmatter) => {
+    if (frontmatter === undefined) {
+        return { contentRoot: root, maybeFrontmatter: Option.none() };
+    }
+    return pipe(root.children, Array.head, Option.filter(isYamlNode), Option.match({
+        onNone: () => ({
+            contentRoot: root,
+            maybeFrontmatter: Option.none(),
+        }),
+        onSome: (yamlNode) => {
+            const parsedFields = parseFrontmatterFields(yamlNode.value, yamlNode.position);
+            validateFrontmatterFields(frontmatter, parsedFields, yamlNode.position);
+            return {
+                contentRoot: { ...root, children: root.children.slice(1) },
+                maybeFrontmatter: Option.some(parsedFields.fields),
+            };
+        },
+    }));
+};
+const parseWithValidatedOptions = (source, options) => {
+    const { contentRoot, maybeFrontmatter } = extractFrontmatter(processor.parse(source), options.frontmatter);
+    return {
+        document: normalizeRoot(contentRoot, options),
+        maybeFrontmatter,
+    };
+};
 /**
  * Parses markdown source into a typed {@link MarkdownDocument}. Throws on any
  * construct outside the markdown vocabulary, and on malformed options. The
  * {@link markdown} plugin runs this per `.md` module; call it directly for
- * one-off compilation in scripts.
+ * one-off compilation in scripts. Frontmatter, when enabled via the
+ * `frontmatter` option, is validated and dropped; use
+ * {@link parseMarkdownWithFrontmatter} to read it.
+ */
+export const parseMarkdown = (source, options = {}) => parseWithValidatedOptions(source, validateMarkdownPluginOptions(options))
+    .document;
+/**
+ * Like {@link parseMarkdown}, but also returns the document's frontmatter
+ * fields when the `frontmatter` option is set and the source carries a
+ * frontmatter block. The fields arrive as the raw strings the block declares,
+ * already validated against the schema, so decoding them with the same schema
+ * cannot fail.
  */
-export const parseMarkdown = (source, options = {}) => parseWithValidatedOptions(source, validateMarkdownPluginOptions(options));
+export const parseMarkdownWithFrontmatter = (source, options = {}) => parseWithValidatedOptions(source, validateMarkdownPluginOptions(options));
 /**
  * Vite plugin that compiles imported `.md` files at build time into typed
  * document modules. Decode the default export with `decodeDocument` and
- * render it with `Markdown.view`.
+ * render it with `Markdown.view`. Every module also carries a `frontmatter`
+ * named export: with a `frontmatter` schema configured, it holds the
+ * document's validated frontmatter fields, and it is `undefined` when the
+ * document has no frontmatter block.
  */
 export const markdown = (options = {}) => {
     const validatedOptions = validateMarkdownPluginOptions(options);
@@ -48,9 +94,17 @@ export const markdown = (options = {}) => {
             if (!id.endsWith('.md')) {
                 return undefined;
             }
-            const document = parseWithValidatedOptions(source, validatedOptions);
+            const { document, maybeFrontmatter } = parseWithValidatedOptions(source, validatedOptions);
+            const documentExport = `export default ${JSON.stringify(encodeDocument(document))}`;
+            // NOTE: `frontmatter` is emitted for every module, `undefined` when the
+            // document has no frontmatter block, so the export always exists and the
+            // `*.md` ambient declaration cannot promise an export a module lacks.
+            const frontmatterExport = Option.match(maybeFrontmatter, {
+                onNone: () => 'undefined',
+                onSome: fields => JSON.stringify(fields),
+            });
             return {
-                code: `export default ${JSON.stringify(encodeDocument(document))}`,
+                code: `${documentExport}\nexport const frontmatter = ${frontmatterExport}`,
                 map: null,
             };
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/markdown",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Write markdown files, get Foldkit views with live islands.",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
     "content.d.ts"
   ],
   "peerDependencies": {
-    "effect": "4.0.0-beta.102",
+    "effect": "4.0.0-beta.105",
     "foldkit": "^0",
     "vite": "^7.0.0 || ^8.0.0"
   },
@@ -39,14 +39,14 @@
   "devDependencies": {
     "@types/mdast": "^4.0.4",
     "@types/unist": "^3.0.3",
-    "effect": "4.0.0-beta.102",
+    "effect": "4.0.0-beta.105",
     "happy-dom": "^20.10.4",
     "mdast-util-directive": "^3.1.0",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.9",
-    "foldkit": "0.134.0"
+    "foldkit": "0.141.1"
   },
   "keywords": [
     "foldkit",