mdx-blog-core 0.1.0

package/README.md

@@ -0,0 +1,340 @@
+# mdx-blog-core
+
+Headless utilities for **MDX- or Markdown-based blogs** in **Next.js** (App Router) and other React apps.
+
+**This package does not render UI or compile MDX.** You keep your own MDX pipeline (`next-mdx-remote`, `next-mdx-rsc`, custom loaders, etc.) and your own React components. `mdx-blog-core` focuses on **loading posts from disk**, **TOC extraction**, **RSS XML**, **neighbour navigation**, **search filtering**, and **LLM-oriented markdown shells**.
+
+Optional companion: `**mdx-blog-ui`** (copy-paste blog UI via CLI from the same workspace)—separate package, not required for `mdx-blog-core`.
+
+---
+
+## Install
+
+```bash
+npm install mdx-blog-core
+# or
+pnpm add mdx-blog-core
+# or
+yarn add mdx-blog-core
+```
+
+### Peer dependencies
+
+
+| Package   | Required          | Notes                                                                    |
+| --------- | ----------------- | ------------------------------------------------------------------------ |
+| **react** | Yes (`>=18`)      | Used by `React.cache` in the Node loader and by client entry points.     |
+| **next**  | Optional (`>=14`) | Only needed if you import `mdx-blog-core/next` (uses `next/navigation`). |
+
+
+Runtime **Node.js** is required for `mdx-blog-core/node` (filesystem access).
+
+### Transitive dependencies
+
+The package depends on `**gray-matter`** (frontmatter) and `**fumadocs-core**` (table of contents). You do not need to install those separately for normal use.
+
+---
+
+## Package entry points
+
+Use the subpath that matches **where your code runs** (Node server vs browser).
+
+
+| Import                | Environment          | Purpose                                                                     |
+| --------------------- | -------------------- | --------------------------------------------------------------------------- |
+| `mdx-blog-core`       | Server / shared      | Types, post helpers, TOC, RSS, LLM markdown helpers, `escapeXml`            |
+| `mdx-blog-core/node`  | **Node only**        | `createBlogSource` — read `.md`/`.mdx` from disk, cached with `React.cache` |
+| `mdx-blog-core/react` | **Client**           | `useFilteredPosts` — memoized filter by title/description query             |
+| `mdx-blog-core/next`  | **Client** (Next.js) | `PostKeyboardNavigation`, `usePostKeyboardNavigation` — arrow-key prev/next |
+
+
+**Important:** Import `mdx-blog-core/node` only from code that runs in the **Node.js** runtime (e.g. Next.js Server Components, `getStaticProps`-style data loaders), not from Edge bundles if your toolchain cannot resolve `node:fs`.
+
+---
+
+## Types (`mdx-blog-core`)
+
+These shapes match what `createBlogSource` expects by default; you can extend metadata with `parseMetadata` + generics.
+
+### `PostMetadata`
+
+
+| Field         | Type       | Description                                                   |
+| ------------- | ---------- | ------------------------------------------------------------- |
+| `title`       | `string`   | Post title                                                    |
+| `description` | `string`   | Short summary                                                 |
+| `image`       | `string?`  | Cover / OG image URL                                          |
+| `category`    | `string?`  | Used with `getPostsByCategory` / `filterPostsByCategory`      |
+| `new`         | `boolean?` | Optional flag for UI                                          |
+| `pinned`      | `boolean?` | Pinned posts sort first (see `sortPostsByPinnedAndCreatedAt`) |
+| `createdAt`   | `string`   | ISO date string (sorting)                                     |
+| `updatedAt`   | `string`   | ISO date string                                               |
+
+
+### `Post`
+
+```ts
+type Post = {
+  metadata: PostMetadata
+  slug: string
+  content: string // body without frontmatter (MDX/Markdown)
+}
+```
+
+### `FsPost` (`mdx-blog-core/node`)
+
+Same as a `Post` for `metadata`, `slug`, and `content`, plus:
+
+- `filePath: string` — absolute path to the source file.
+
+### `PostPreview`
+
+Minimal shape: `{ slug, title, category? }` for list UIs that should not ship full `content`.
+
+### `TOCItemType`
+
+Re-exported from `fumadocs-core/toc`. Returned items from `getTableOfContents` include `title`, `url`, `depth`, etc.—use them in your own TOC component.
+
+---
+
+## Loading content: `createBlogSource` (`mdx-blog-core/node`)
+
+```ts
+import { createBlogSource } from "mdx-blog-core/node"
+
+const blog = createBlogSource({
+  contentDir: "content/blog",
+  extensions: [".mdx", ".md"],
+  recursive: true,
+})
+
+const all = blog.getAllPosts()
+const one = blog.getPostBySlug("my-post")
+const guides = blog.getPostsByCategory("guides")
+```
+
+### Options
+
+
+| Option                 | Type       | Default                   | Description                                                                                           |
+| ---------------------- | ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `contentDir`           | `string`   | (required)                | Absolute path, or relative to `process.cwd()`                                                         |
+| `extensions`           | `string[]` | `[".mdx"]`                | Allowed file extensions (case-insensitive)                                                            |
+| `recursive`            | `boolean`  | `false`                   | If `true`, walk subfolders; slug becomes path relative to `contentDir` with `/` (e.g. `guides/hello`) |
+| `parseMetadata`        | function   | identity cast             | `(data, { filePath, slug }) => Meta` — use **Zod** (or similar) here                                  |
+| `sort`                 | function   | pinned + `createdAt` desc | Custom sort; affects neighbour order                                                                  |
+| `throwOnDuplicateSlug` | `boolean`  | `true`                    | Throw if two files resolve to the same slug                                                           |
+
+
+### Slug rules
+
+- **Flat directory:** slug = filename without extension (`hello.mdx` → `hello`).
+- **Recursive:** slug = relative path without extension, POSIX-style (`guides/hello.mdx` → `guides/hello`).
+
+### Caching
+
+`getAllPosts` is wrapped in `**React.cache`**, so within a single request the file system is read once. Ensure this module is only used in contexts where React’s cache is valid (RSC / Next data layer).
+
+### Example frontmatter
+
+```yaml
+---
+title: "Hello world"
+description: "A short summary for lists and RSS."
+createdAt: "2026-04-01"
+updatedAt: "2026-04-05"
+category: "guides"
+image: "/og/hello.png"
+pinned: false
+new: true
+---
+
+Your MDX body starts here.
+```
+
+### Validating frontmatter with Zod
+
+```ts
+import { z } from "zod"
+import { createBlogSource } from "mdx-blog-core/node"
+import type { PostMetadata } from "mdx-blog-core"
+
+const Schema = z.object({
+  title: z.string(),
+  description: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  category: z.string().optional(),
+  image: z.string().optional(),
+  pinned: z.boolean().optional(),
+  new: z.boolean().optional(),
+}) satisfies z.ZodType<PostMetadata>
+
+const blog = createBlogSource({
+  contentDir: "content/blog",
+  parseMetadata: (data, _ctx) => Schema.parse(data),
+})
+```
+
+---
+
+## Table of contents (`mdx-blog-core`)
+
+```ts
+import { getTableOfContents, type TOCItemType } from "mdx-blog-core"
+
+const items = getTableOfContents(post.content)
+```
+
+Uses **fumadocs-core**’s TOC extractor on the **raw** MDX/Markdown string. Heading IDs in the rendered page should match `item.url` fragments (e.g. `#section-id`)—configure your MDX pipeline (e.g. `rehype-slug`) accordingly.
+
+---
+
+## Previous / next post (`mdx-blog-core`)
+
+```ts
+import { findNeighbour } from "mdx-blog-core"
+
+const { previous, next } = findNeighbour(allPosts, currentSlug)
+```
+
+Order matches the **array order** of `allPosts` (usually your sorted list from `getAllPosts()`). If the slug is missing, both neighbours are `null`.
+
+---
+
+## Sorting and filters (`mdx-blog-core`)
+
+```ts
+import {
+  sortPostsByPinnedAndCreatedAt,
+  filterPostsByCategory,
+  filterPostsByQuery,
+} from "mdx-blog-core"
+
+posts.sort(sortPostsByPinnedAndCreatedAt)
+const guides = filterPostsByCategory(posts, "guides")
+const hits = filterPostsByQuery(posts, searchQuery)
+```
+
+`filterPostsByQuery` normalizes spaces and case; it matches **title** and **description** substrings.
+
+---
+
+## RSS (`mdx-blog-core`)
+
+```ts
+import { buildRssFeedXml, type RssChannelInfo, type RssFeedItem } from "mdx-blog-core"
+
+const channel: RssChannelInfo = {
+  title: "My blog",
+  link: "https://example.com",
+  description: "Latest posts",
+}
+
+const items: RssFeedItem[] = posts.map((p) => ({
+  title: p.metadata.title,
+  link: `${siteUrl}/blog/${p.slug}`,
+  description: p.metadata.description,
+  pubDate: p.metadata.createdAt,
+}))
+
+const xml = buildRssFeedXml(channel, items)
+```
+
+`escapeXml` is used internally; export it if you build custom XML.
+
+**Next.js App Router example** (`app/blog/rss.xml/route.ts` or similar):
+
+```ts
+import { buildRssFeedXml } from "mdx-blog-core"
+
+export function GET() {
+  const xml = buildRssFeedXml(channel, items)
+  return new Response(xml, {
+    headers: { "Content-Type": "application/rss+xml; charset=utf-8" },
+  })
+}
+```
+
+---
+
+## LLM / plain markdown export (`mdx-blog-core`)
+
+For “view as markdown” or RAG-friendly text, process MDX with **your own** `remark`/`unified` pipeline, then wrap:
+
+```ts
+import { buildLlmMarkdownDocument } from "mdx-blog-core"
+
+const markdown = buildLlmMarkdownDocument({
+  title: post.metadata.title,
+  description: post.metadata.description,
+  bodyMarkdown: processedBody,
+  updatedAtLabel: "April 5, 2026",
+})
+```
+
+Or use `**buildLlmMarkdownFromPost**` when you want the package to assemble title, description, and “Last updated” around an async body converter:
+
+```ts
+import { buildLlmMarkdownFromPost } from "mdx-blog-core"
+
+const markdown = await buildLlmMarkdownFromPost({
+  post,
+  toBodyMarkdown: async ({ content }) => {
+    // run remark/rehype here; return plain markdown string
+    return content
+  },
+  getUpdatedAtLabel: ({ updatedAt }) => updatedAt,
+})
+```
+
+---
+
+## Client: search list (`mdx-blog-core/react`)
+
+```tsx
+"use client"
+
+import { useFilteredPosts } from "mdx-blog-core/react"
+
+const visible = useFilteredPosts(posts, query)
+```
+
+Pass `query` from URL state (`nuqs`, `useSearchParams`, etc.). `null`/`undefined`/empty string returns all posts.
+
+---
+
+## Client: keyboard navigation (`mdx-blog-core/next`)
+
+Requires **Next.js** (`next/navigation`).
+
+```tsx
+"use client"
+
+import { PostKeyboardNavigation } from "mdx-blog-core/next"
+
+export function BlogPostChrome({
+  basePath,
+  previous,
+  next,
+}: {
+  basePath: string
+  previous: { slug: string } | null
+  next: { slug: string } | null
+}) {
+  return (
+    <PostKeyboardNavigation
+      basePath={basePath.replace(/\/$/, "")}
+      previous={previous}
+      next={next}
+    />
+  )
+}
+```
+
+**ArrowLeft** / **ArrowRight** navigate when `defaultPrevented` is false on the key event. For custom routing, use `**usePostKeyboardNavigation`** with your own `push` function.
+
+
+## License
+
+MIT

package/dist/core.d.ts

@@ -0,0 +1,84 @@
+import { getTableOfContents } from "fumadocs-core/content/toc";
+export type { TOCItemType } from "fumadocs-core/toc";
+export type PostMetadata = {
+    title: string;
+    description: string;
+    image?: string;
+    category?: string;
+    new?: boolean;
+    pinned?: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+export type Post = {
+    metadata: PostMetadata;
+    slug: string;
+    content: string;
+};
+export type PostPreview = {
+    slug: string;
+    title: string;
+    category?: string;
+};
+export declare function sortPostsByPinnedAndCreatedAt(a: Post, b: Post): number;
+export declare function filterPostsByCategory(posts: Post[], category: string): Post[];
+export declare function findNeighbour<T extends {
+    slug: string;
+}>(posts: T[], slug: string): {
+    previous: T | null;
+    next: T | null;
+};
+export declare function filterPostsByQuery<T extends {
+    metadata: {
+        title: string;
+        description: string;
+    };
+}>(posts: T[], query: string | null): T[];
+export declare function escapeXml(text: string): string;
+export type RssChannelInfo = {
+    title: string;
+    link: string;
+    description: string;
+};
+export type RssFeedItem = {
+    title: string;
+    link: string;
+    description: string;
+    pubDate: Date | string;
+};
+export declare function buildRssFeedXml(channel: RssChannelInfo, items: RssFeedItem[]): string;
+export declare function buildLlmMarkdownDocument(parts: {
+    title: string;
+    description: string;
+    bodyMarkdown: string;
+    updatedAtLabel: string;
+}): string;
+export type LlmPostLike = {
+    metadata: {
+        title: string;
+        description: string;
+        updatedAt: string;
+    };
+    content: string;
+};
+export declare function buildLlmMarkdownFromPost<TPost extends LlmPostLike>(params: {
+    post: TPost;
+    /**
+     * Convert raw MDX/Markdown into a plain-markdown body suitable for LLM consumption.
+     * The host app fully owns the processor (remark/unified/CMS/etc).
+     */
+    toBodyMarkdown: (input: {
+        content: string;
+        post: TPost;
+    }) => Promise<string>;
+    /**
+     * Provide the human-readable updated-at label. This keeps the package unopinionated
+     * about date formatting libraries and locales.
+     */
+    getUpdatedAtLabel: (input: {
+        updatedAt: string;
+        post: TPost;
+    }) => string;
+}): Promise<string>;
+export { getTableOfContents };
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

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

package/dist/core.js

@@ -0,0 +1,90 @@
+import { getTableOfContents } from "fumadocs-core/content/toc";
+export function sortPostsByPinnedAndCreatedAt(a, b) {
+    if (a.metadata.pinned && !b.metadata.pinned)
+        return -1;
+    if (!a.metadata.pinned && b.metadata.pinned)
+        return 1;
+    return (new Date(b.metadata.createdAt).getTime() -
+        new Date(a.metadata.createdAt).getTime());
+}
+export function filterPostsByCategory(posts, category) {
+    return posts.filter((post) => post.metadata.category === category);
+}
+export function findNeighbour(posts, slug) {
+    const len = posts.length;
+    for (let i = 0; i < len; ++i) {
+        if (posts[i].slug === slug) {
+            return {
+                previous: i > 0 ? posts[i - 1] : null,
+                next: i < len - 1 ? posts[i + 1] : null,
+            };
+        }
+    }
+    return { previous: null, next: null };
+}
+const normalize = (text) => text.toLowerCase().replaceAll(" ", "");
+function matchesQuery(post, normalizedQuery) {
+    const normalizedTitle = normalize(post.metadata.title);
+    const normalizedDescription = normalize(post.metadata.description);
+    return (normalizedTitle.includes(normalizedQuery) ||
+        normalizedDescription.includes(normalizedQuery));
+}
+export function filterPostsByQuery(posts, query) {
+    if (!query)
+        return posts;
+    const normalizedQuery = normalize(query);
+    return posts.filter((post) => matchesQuery(post, normalizedQuery));
+}
+export function escapeXml(text) {
+    return text
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+export function buildRssFeedXml(channel, items) {
+    const itemsXml = items
+        .map((post) => `<item>
+          <title>${escapeXml(post.title)}</title>
+          <link>${escapeXml(post.link)}</link>
+          <description>${escapeXml(post.description)}</description>
+          <pubDate>${new Date(post.pubDate).toUTCString()}</pubDate>
+        </item>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8" ?>
+  <rss version="2.0">
+    <channel>
+      <title>${escapeXml(channel.title)}</title>
+      <link>${escapeXml(channel.link)}</link>
+      <description>${escapeXml(channel.description)}</description>
+      ${itemsXml}
+    </channel>
+  </rss>`;
+}
+export function buildLlmMarkdownDocument(parts) {
+    return `# ${parts.title}
+
+${parts.description}
+
+${parts.bodyMarkdown}
+
+Last updated on ${parts.updatedAtLabel}`;
+}
+export async function buildLlmMarkdownFromPost(params) {
+    const bodyMarkdown = await params.toBodyMarkdown({
+        content: params.post.content,
+        post: params.post,
+    });
+    const updatedAtLabel = params.getUpdatedAtLabel({
+        updatedAt: params.post.metadata.updatedAt,
+        post: params.post,
+    });
+    return buildLlmMarkdownDocument({
+        title: params.post.metadata.title,
+        description: params.post.metadata.description,
+        bodyMarkdown,
+        updatedAtLabel,
+    });
+}
+export { getTableOfContents };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { buildLlmMarkdownDocument, buildLlmMarkdownFromPost, buildRssFeedXml, escapeXml, filterPostsByCategory, filterPostsByQuery, findNeighbour, getTableOfContents, type LlmPostLike, type Post, type PostMetadata, type PostPreview, type RssChannelInfo, type RssFeedItem, sortPostsByPinnedAndCreatedAt, type TOCItemType, } from "./core.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,eAAe,EACf,SAAS,EACT,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,IAAI,EACT,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,6BAA6B,EAC7B,KAAK,WAAW,GACjB,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { buildLlmMarkdownDocument, buildLlmMarkdownFromPost, buildRssFeedXml, escapeXml, filterPostsByCategory, filterPostsByQuery, findNeighbour, getTableOfContents, sortPostsByPinnedAndCreatedAt, } from "./core.js";

package/dist/next.d.ts

@@ -0,0 +1,15 @@
+export type PostNavTarget = {
+    slug: string;
+};
+export declare function usePostKeyboardNavigation(options: {
+    basePath: string;
+    previous: PostNavTarget | null;
+    next: PostNavTarget | null;
+    push: (href: string) => void;
+}): void;
+export declare function PostKeyboardNavigation({ basePath, previous, next, }: {
+    basePath: string;
+    previous: PostNavTarget | null;
+    next: PostNavTarget | null;
+}): null;
+//# sourceMappingURL=next.d.ts.map

package/dist/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../src/next.tsx"],"names":[],"mappings":"AAKA,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5C,wBAAgB,yBAAyB,CAAC,OAAO,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAA;IAC9B,IAAI,EAAE,aAAa,GAAG,IAAI,CAAA;IAC1B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7B,GAAG,IAAI,CAmBP;AAED,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,QAAQ,EACR,IAAI,GACL,EAAE;IACD,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAA;IAC9B,IAAI,EAAE,aAAa,GAAG,IAAI,CAAA;CAC3B,QAaA"}

package/dist/next.js

@@ -0,0 +1,33 @@
+"use client";
+import { useRouter } from "next/navigation";
+import { useEffect } from "react";
+export function usePostKeyboardNavigation(options) {
+    const { basePath, previous, next, push } = options;
+    useEffect(() => {
+        const onKeyDown = (event) => {
+            if (event.defaultPrevented) {
+                return;
+            }
+            if (event.key === "ArrowRight" && next) {
+                push(`${basePath}/${next.slug}`);
+            }
+            else if (event.key === "ArrowLeft" && previous) {
+                push(`${basePath}/${previous.slug}`);
+            }
+        };
+        window.addEventListener("keydown", onKeyDown);
+        return () => window.removeEventListener("keydown", onKeyDown);
+    }, [basePath, next, previous, push]);
+}
+export function PostKeyboardNavigation({ basePath, previous, next, }) {
+    const router = useRouter();
+    usePostKeyboardNavigation({
+        basePath,
+        previous,
+        next,
+        push: (href) => {
+            router.push(href);
+        },
+    });
+    return null;
+}

package/dist/node.d.ts

@@ -0,0 +1,67 @@
+import type { PostMetadata } from "./core.js";
+export type FsPost<Meta extends Record<string, unknown> = PostMetadata> = {
+    metadata: Meta;
+    /**
+     * Slug derived from the filename.
+     *
+     * - When `recursive: false`: `hello-world`
+     * - When `recursive: true`: `guides/hello-world`
+     */
+    slug: string;
+    /** Raw markdown/MDX body without frontmatter. */
+    content: string;
+    /** Absolute file path to the source. */
+    filePath: string;
+};
+type ParseFrontmatterContext = {
+    filePath: string;
+    slug: string;
+};
+export type FrontmatterParser<Meta extends Record<string, unknown> = PostMetadata> = (data: unknown, ctx: ParseFrontmatterContext) => Meta;
+export type BlogSourceOptions<Meta extends Record<string, unknown> = PostMetadata> = {
+    /**
+     * Directory containing markdown/MDX files.
+     *
+     * Accepts an absolute path or a path relative to `process.cwd()`.
+     */
+    contentDir: string;
+    /**
+     * File extensions to include (case-insensitive).
+     *
+     * @defaultValue [".mdx"]
+     */
+    extensions?: string[];
+    /**
+     * Recursively discover files under `contentDir`.
+     *
+     * @defaultValue false
+     */
+    recursive?: boolean;
+    /**
+     * Parse/validate frontmatter. Use this for Zod validation, default values, etc.
+     *
+     * @defaultValue (data) => data as PostMetadata
+     */
+    parseMetadata?: FrontmatterParser<Meta>;
+    /**
+     * Override default sort (pinned first, then `createdAt` descending).
+     *
+     * Note: sorting affects neighbour navigation ordering in the host app.
+     */
+    sort?: (a: FsPost<Meta>, b: FsPost<Meta>) => number;
+    /**
+     * If true, throw on duplicate slugs. This catches collisions that can happen
+     * with case-insensitive filesystems or nested files.
+     *
+     * @defaultValue true
+     */
+    throwOnDuplicateSlug?: boolean;
+};
+export type BlogSource<Meta extends Record<string, unknown> = PostMetadata> = {
+    getAllPosts: () => FsPost<Meta>[];
+    getPostBySlug: (slug: string) => FsPost<Meta> | undefined;
+    getPostsByCategory: (category: string) => FsPost<Meta>[];
+};
+export declare function createBlogSource<Meta extends Record<string, unknown> = PostMetadata>(options: BlogSourceOptions<Meta>): BlogSource<Meta>;
+export {};
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAQ,YAAY,EAAE,MAAM,WAAW,CAAA;AAGnD,MAAM,MAAM,MAAM,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,IAAI;IACxE,QAAQ,EAAE,IAAI,CAAA;IACd;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,KAAK,uBAAuB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,iBAAiB,CAC3B,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,IACjD,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,uBAAuB,KAAK,IAAI,CAAA;AAezD,MAAM,MAAM,iBAAiB,CAC3B,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,IACjD;IACF;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAA;IACvC;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,MAAM,CAAA;IACnD;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B,CAAA;AAED,MAAM,MAAM,UAAU,CACpB,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,IACjD;IACF,WAAW,EAAE,MAAM,MAAM,CAAC,IAAI,CAAC,EAAE,CAAA;IACjC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,CAAA;IACzD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,EAAE,CAAA;CACzD,CAAA;AAgDD,wBAAgB,gBAAgB,CAC9B,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,EACnD,OAAO,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CA6EpD"}

package/dist/node.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { cache } from "react";
+import { sortPostsByPinnedAndCreatedAt } from "./core.js";
+function parseFrontmatter(fileContent, ctx, parseMeta) {
+    const file = matter(fileContent);
+    return {
+        metadata: parseMeta(file.data, ctx),
+        content: file.content,
+    };
+}
+function normalizeExtList(exts) {
+    return new Set(exts.map((e) => e.toLowerCase()));
+}
+function listFilesRecursive(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...listFilesRecursive(full));
+        }
+        else if (entry.isFile()) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+function listFilesFlat(dir) {
+    return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile())
+        .map((e) => path.join(dir, e.name));
+}
+function toPosixPath(p) {
+    return p.replaceAll(path.sep, "/");
+}
+function getSlugFromFilePath(params) {
+    if (!params.recursive) {
+        const base = path.basename(params.filePath);
+        return path.basename(base, path.extname(base));
+    }
+    const rel = path.relative(params.contentDir, params.filePath);
+    const withoutExt = rel.slice(0, rel.length - path.extname(rel).length);
+    return toPosixPath(withoutExt);
+}
+export function createBlogSource(options) {
+    const contentDir = path.isAbsolute(options.contentDir)
+        ? options.contentDir
+        : path.join(process.cwd(), options.contentDir);
+    const recursive = options.recursive ?? false;
+    const extensions = normalizeExtList(options.extensions ?? [".mdx"]);
+    const throwOnDuplicateSlug = options.throwOnDuplicateSlug ?? true;
+    const parseMetadata = options.parseMetadata ?? ((data) => data);
+    const sort = options.sort ??
+        ((a, b) => sortPostsByPinnedAndCreatedAt(a, b));
+    function readAllPosts() {
+        const files = recursive
+            ? listFilesRecursive(contentDir)
+            : listFilesFlat(contentDir);
+        const posts = files
+            .filter((filePath) => extensions.has(path.extname(filePath).toLowerCase()))
+            .map((filePath) => {
+            const slug = getSlugFromFilePath({
+                contentDir,
+                filePath,
+                recursive,
+            });
+            const rawContent = fs.readFileSync(filePath, "utf-8");
+            const { metadata, content } = parseFrontmatter(rawContent, { filePath, slug }, parseMetadata);
+            return {
+                metadata,
+                slug,
+                content,
+                filePath,
+            };
+        });
+        if (throwOnDuplicateSlug) {
+            const seen = new Map();
+            for (const post of posts) {
+                const prior = seen.get(post.slug);
+                if (prior != null) {
+                    throw new Error(`Duplicate slug \"${post.slug}\" found in:\n- ${prior}\n- ${post.filePath}`);
+                }
+                seen.set(post.slug, post.filePath);
+            }
+        }
+        return [...posts].sort(sort);
+    }
+    const getAllPosts = cache(readAllPosts);
+    return {
+        getAllPosts,
+        getPostBySlug(slug) {
+            return getAllPosts().find((post) => post.slug === slug);
+        },
+        getPostsByCategory(category) {
+            return getAllPosts().filter((post) => post.metadata.category === category);
+        },
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,7 @@
+export declare function useFilteredPosts<T extends {
+    metadata: {
+        title: string;
+        description: string;
+    };
+}>(posts: T[], query: string | null | undefined): T[];
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAMA,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS;IAAE,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAC9D,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,EAAE,CAKnD"}

package/dist/react.js

@@ -0,0 +1,6 @@
+"use client";
+import { useMemo } from "react";
+import { filterPostsByQuery } from "./core.js";
+export function useFilteredPosts(posts, query) {
+    return useMemo(() => filterPostsByQuery(posts, query ?? null), [posts, query]);
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "mdx-blog-core",
+  "version": "0.1.0",
+  "description": "Headless MDX blog utilities for Next.js: filesystem loading, TOC, RSS, neighbours, search filter, LLM markdown shell.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc -p tsconfig.build.json --noEmit"
+  },
+  "dependencies": {
+    "fumadocs-core": "^16.6.8",
+    "gray-matter": "^4.0.3"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.12",
+    "@types/react": "19.2.10",
+    "next": "16.1.6",
+    "react": "19.2.4",
+    "typescript": "5.8.3"
+  }
+}