@bliztek/mdx-utils

Zero-dependency MDX content utilities for read time calculation and file discovery.

Installation

npm install @bliztek/mdx-utils

Usage

Pure Utilities (any JS environment)

import {
  calculateReadTime,
  sortByDateDescending,
  stripMdxSyntax,
} from "@bliztek/mdx-utils";

// Calculate read time from raw MDX content
const { minutes, words } = calculateReadTime(mdxContent);
// => { minutes: 5, words: 1190 }

// Custom words per minute
const { minutes } = calculateReadTime(technicalDoc, { wordsPerMinute: 150 });

// Strip MDX syntax for excerpts, search indexes, or OG descriptions
const plainText = stripMdxSyntax(mdxContent);

// Sort items by date (newest first)
const sorted = sortByDateDescending(posts, (post) => post.date);

Node.js Utilities

import { getContentSlugs, readMdxFile } from "@bliztek/mdx-utils/node";

// Get all MDX slugs from a directory
const slugs = await getContentSlugs("./content/blog");
// => ["my-first-post", "another-post"]

// Include .md files too
const all = await getContentSlugs("./content", {
  extensions: [".mdx", ".md"],
});

// Recursively search nested directories
const nested = await getContentSlugs("./content/blog", { recursive: true });
// => ["my-first-post", "2024/year-in-review"]

// Read an MDX file
const content = await readMdxFile("./content/blog/my-first-post.mdx");

API

calculateReadTime(content, options?)

Calculates estimated read time for MDX/markdown content. Strips export blocks, import statements, JSX tags, and markdown syntax before counting words.

Returns { minutes: number, words: number } — minutes is always at least 1.

| Option | Type | Default | Description | |--------|------|---------|-------------| | wordsPerMinute | number | 238 | Reading speed to use for calculation |

stripMdxSyntax(content)

Strips MDX/markdown syntax from content, returning plain text. Removes export blocks, import statements, JSX tags, and markdown formatting characters. Useful for generating excerpts, search indexes, or OpenGraph descriptions from raw MDX.

sortByDateDescending(items, getDate)

Sorts items by date in descending order (newest first). Returns a new array without mutating the original. The getDate callback should return a date string parseable by new Date().

getContentSlugs(dirPath, options?)

Reads a directory and returns slugs (filenames without extension) of matching content files. When recursive is true, slugs from subdirectories include their relative path (e.g., "2024/my-post").

| Option | Type | Default | Description | |--------|------|---------|-------------| | extensions | string[] | [".mdx"] | File extensions to include | | recursive | boolean | false | Search subdirectories |

readMdxFile(filePath)

Reads a file and returns its content as a UTF-8 string.

Types

type TableOfContentsEntry = { title: string; link: string };
type TableOfContents = TableOfContentsEntry[];

interface ReadTimeOptions { wordsPerMinute?: number }
interface ReadTimeResult { minutes: number; words: number }
interface GetContentSlugsOptions { extensions?: string[]; recursive?: boolean }

Entry Points

| Import | Environment | Contents | |--------|------------|----------| | @bliztek/mdx-utils | Any (browser, edge, Node) | calculateReadTime, stripMdxSyntax, sortByDateDescending, types | | @bliztek/mdx-utils/node | Node.js | getContentSlugs, readMdxFile + re-exports from main |

License

MIT