File-based markdown blogging for modern web apps. Type-safe, framework-agnostic, zero-config.
Drop markdown files in a folder, get a fully typed blog: posts, categories, tags, search, related posts, RSS, sitemap, OG images, JSON-LD, and llms.txt — with adapters for Next.js, Astro, and plain React.
content/posts/hello-world.md → https://yoursite.com/blog/hello-world
- Files, not a CMS — posts are markdown files with YAML frontmatter, versioned in git next to your code.
- Type-safe frontmatter — validated with Zod at build time. Extend the schema and your custom fields are typed end to end.
- Framework adapters, one core — the same content model renders in Next.js App Router, Astro Content Layer, or any React app.
- SEO out of the box — RSS 2.0, sitemap, canonical URLs, OpenGraph/Twitter metadata, JSON-LD, and dynamic OG images.
- AI-friendly — generates
llms.txt, ships a search index, and has a content model simple enough that an agent can write and validate posts (docs). - Fails loudly — invalid frontmatter, missing directories, and duplicate slugs throw at build time, not at runtime in production.
npm install @yamblog/core @yamblog/next<!-- content/posts/hello-world.md -->
---
title: "Hello World"
date: 2026-01-15
excerpt: "My first post."
tags: [intro]
---
Welcome to my blog!// lib/blog.ts
import { defineBlog } from '@yamblog/core';
export const blog = defineBlog('content/posts');// app/blog/page.tsx
import { BlogListPage } from '@yamblog/next';
import { blog } from '@/lib/blog';
export default async function Page() {
const posts = await blog.getPosts();
return <BlogListPage posts={posts} />;
}That's it — see the getting started guide for post pages, RSS, sitemap, and OG images.
| Package | Description |
|---|---|
@yamblog/core |
Framework-agnostic engine: parsing, validation, queries, search, related posts, RSS, sitemap, llms.txt |
@yamblog/next |
Next.js adapter: App Router metadata, JSON-LD, RSS/sitemap handlers, OG image routes, page components |
@yamblog/react |
React adapter: markdown renderer, client-side search hook, UI components |
@yamblog/astro |
Astro adapter: Content Layer loader and .astro page components |
@yamblog/remark |
Remark/rehype plugins: table of contents, embeds, interactive blocks |
const posts = await blog.getPosts(); // all published posts, newest first
const post = await blog.getPostBySlug('hello'); // throws if missing
const maybe = await blog.findPostBySlug('hello'); // null if missing
const tagged = await blog.getPostsByTag('react');
const results = await blog.search('typescript');
const related = await blog.getRelatedPosts('hello');
const adjacent = await blog.getAdjacentPosts('hello');
const rss = await blog.generateRss({ title: 'My Blog', description: '…' });
const sitemap = await blog.generateSitemap();
const llms = await blog.generateLlmsTxt();Every method also has a synchronous twin (getPostsSync(), generateRssSync(…), …)
for Pages Router, module-scope constants, and standalone build scripts. Missing
posts throw a typed PostNotFoundError — catch with instanceof, no string matching.
Custom typed frontmatter:
import { defineBlog, defaultSchema } from '@yamblog/core';
import { z } from 'zod';
export const blog = defineBlog({
contentDir: 'content/posts',
schema: defaultSchema.extend({
videoUrl: z.string().url().optional(),
}),
});
const post = await blog.getPostBySlug('hello');
post.videoUrl; // string | undefined — typed automatically, no castsNote:
.mdxfiles are picked up alongside.md, but content is rendered as plain markdown — JSX/MDX components are not executed.
Runnable apps for each framework live in examples/:
with-next · with-astro · with-react
- Website: yamblog.dev
- Getting started
- Architecture · Extensibility · AI-agent authoring · llms.txt
- Recipes: Next.js · Astro · React · Custom fields
Contributions are welcome! See CONTRIBUTING.md for local setup and workflow, and RELEASING.md for how releases are published.