Skip to content
yamblogPublic

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

YAMBLOG

File-based markdown blogging for modern web apps. Type-safe, framework-agnostic, zero-config.

CI npm license

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

Why YAMBLOG?

  • 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.

Quick start (Next.js)

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.

Packages

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

Core API at a glance

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 casts

Note: .mdx files are picked up alongside .md, but content is rendered as plain markdown — JSX/MDX components are not executed.

Examples

Runnable apps for each framework live in examples/: with-next · with-astro · with-react

Documentation

Contributing

Contributions are welcome! See CONTRIBUTING.md for local setup and workflow, and RELEASING.md for how releases are published.

License

MIT © Bharat Parsiya

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages