A static Markdown blog for any Vite site, without a second framework.
Each post becomes a plain HTML page built from your own page shell, so your header,
scripts, styles and transformIndexHtml plugins apply to posts like to every other page.
- Posts are HTML in the page source. A post reads with no JavaScript.
- Works under a strict Content Security Policy. Nothing the plugin writes needs an
inline script or
styleattribute. Code is highlighted with Shiki at build time, as classes, and the announcement banner's script and styles are files. - Checks every post. The build fails, naming the file and line, on a missing or
too-long title or description, a bad date, a tag not in
tags.yml, an image without alt text or without a file, or a link to a page that doesn't exist (or to a draft). - Lists people can find their way around: an index at
/blog/with a featured post, a page per topic, pinned posts first, cards, numbered pages at.../page/2/, and breadcrumbs back up. A browse bar puts the topics on one line as tabs with post counts, with a date menu (years and months) and a feed icon at its end. - Search without a server. A
search.jsonindex built with the site, and a search field that ranks, sorts and pages results in the browser, keeps them in the address (?q=dns&date=2026-11&sort=oldest) and loads the index only when someone starts typing. No WebAssembly and no extra build step, so it works underscript-src 'self'. - Reach: share links that load nothing from the networks, feed links on every page,
a subscribe dialog where readers pick RSS, Atom or JSON Feed and copy or open it,
related posts, series navigation, and
virtual:blog/latestfor a home page strip. - An announcement banner across every page of the site for posts marked
announcement, with a count of the others, a close button that remembers, and an optional end date. - RSS, Atom and JSON feeds with whole articles and absolute image addresses, and a sitemap.
- Social cards and search data: Open Graph tags, a stable
og:imagefor the cover (or a site-wide fallback), andBlogPosting,Blog,CollectionPageandBreadcrumbListstructured data. - Optional Vue components and default styles. The same card, pager and search
markup as the static pages, themed with a few
--blog-*custom properties. - Drafts, scheduled and unlisted posts. Drafts and future dates stay out of the
build unless
previewis on. Unlisted posts are built but appear in no list or feed. :::directives.note,tipandwarningcallouts are built in. Add your own, such as a live widget inside a post.- Images next to the post go through Vite (hashed and copied), with
widthandheightset so the page doesn't shift, andloading="lazy"after the first. - Live reload in dev, with problems shown in Vite's error overlay.
virtual:blog/postslists posts for the rest of the site, such as a "Latest posts" strip on the home page.
| This plugin | A docs framework (VitePress, Ox Content) | Markdown-to-HTML plugins | |
|---|---|---|---|
| Your existing Vite site and markup | Yes, your own page shell | No, its theme and router | A template, outside Vite's pipeline |
Works under script-src 'self' |
Yes | Depends on the theme | Often inline scripts |
| Fails the build on broken posts | Yes, by file and line | Dead links only | No |
| Tags, pages, feeds, sitemap | Built in | Built in or by plugin | Feeds and sitemap at most |
| Search with no server or WASM | Built in | Usually a hosted service or WASM | No |
| Site-wide announcement banner | Built in, no inline code | By plugin or theme | No |
If your site is a docs site, use a docs framework (and @binarynoir/vitepress-blog for VitePress). This plugin is for sites that are already plain Vite pages.
npm install --save-dev @binarynoir/vite-plugin-blogNeeds Node 22 or later and Vite 6, 7 or 8.
content/
posts/
vpn-leaks/
index.md # served at /blog/vpn-leaks/
diagram.svg # images sit next to the post
short-post.md # served at /blog/short-post/
tags.yml # optional: the only tags allowed
authors.yml # optional
templates/
post.html # your page shell
// vite.config.ts
import { defineConfig } from "vite";
import { blogPlugin } from "@binarynoir/vite-plugin-blog";
export default defineConfig({
plugins: [
blogPlugin({
dir: "content",
template: "templates/post.html",
site: "https://example.com",
titleSuffix: " · Example",
preview: process.env.BLOG_PREVIEW === "1",
}),
],
});The page shell is any HTML page with two markers, used for posts and lists alike. Use
root paths (/src/post.ts) in it, since pages are served from /blog/{slug}/. Leave out
<title>; the plugin writes it.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<!--blog:head-->
</head>
<body>
<main><!--blog:content--></main>
<script type="module" src="/src/post.ts"></script>
</body>
</html>// src/post.ts
import "virtual:blog/code.css"; // the highlighting classes the posts use
import "@binarynoir/vite-plugin-blog/styles.css"; // optional: default styles
import { enhanceBlogPage } from "@binarynoir/vite-plugin-blog/runtime";
import { mountBlogExplorer } from "@binarynoir/vite-plugin-blog/vue"; // needs vue
enhanceBlogPage(); // copy buttons, "Copy link", contents highlight, subscribe dialog
mountBlogExplorer(); // search on the index and tag pages; does nothing elsewhereEvery page reads without that script. It adds the extras.
For types, add "@binarynoir/vite-plugin-blog/client" to types in tsconfig.json.
title: Is your VPN actually working? # required, 70 characters at most
description: The four leaks to test. # required, 160 characters at most
date: 2026-12-02 # required; a future date schedules the post
updated: 2026-12-10
tags: [vpn-privacy, homelab]
authors: [jane] # ids from authors.yml
series: building-it
cover: cover.png # also the social card image
pinned: true # kept at the top of lists
featured: true # for your own markup
unlisted: true # built, but in no list, feed or sitemap
draft: false
announcement: true # or the banner's text, or { text, until }Fields the plugin doesn't know (tools, discuss) are kept in post.data, for your own
checks and markup.
# authors.yml
jane: { name: Jane Doe, url: https://example.com/jane, email: jane@example.com }Highlighting uses CSS light-dark(), so it follows the page's color-scheme. Set
color-scheme: light dark on :root, and color-scheme: dark or light when your
theme switch picks one.
announcement puts a post in a banner across the top of every page Vite builds, the
site's own pages included:
announcement: true # the banner shows the post's title
announcement: Scheduled maintenance on Friday, 18:00 UTC
announcement:
text: Early pricing ends Friday
until: 2026-12-04 # the end of that day, in the blog's time zone; or a date and time- The newest one shows. With more than one, a badge counts them and links to
/blog/announcements/, which lists them all. - Visitors can close it. The close button dismisses every current announcement, and the browser remembers. A newer announcement brings the banner back.
- No flash on load. A small script in
<head>hides a dismissed banner before the page draws. It is a file, not inline, soscript-src 'self'allows it. - Ending. After
until, the banner stops showing it, at once in the browser and from the next build on. A daily scheduled build keeps the HTML in step.
| Option | Default | What it does |
|---|---|---|
announcements.placement |
"body" |
"body": first in <body>. "marker": only at <!--blog:announcement--> |
announcements.include |
every page | (path) => boolean, by the page's path: /, /pricing/ |
announcements.styles |
true |
false keeps only the rule that hides a dismissed banner |
announcements.storageKey |
blog-announcements-dismissed |
The localStorage key |
announcements: false turns the banner off. Restyle it with --blog-announcement-bg and
--blog-announcement-color, or your own rules for .blog-announcement,
.blog-announcement-text, .blog-announcement-count and .blog-announcement-dismiss.
The default rules have zero specificity, so yours win.
| Page | Shows |
|---|---|
/blog/ |
Eyebrow, title and lead; search; the browse bar (topic tabs with counts, date menu, feed icon); the featured post; cards; numbered pages; feed links |
/blog/tag/dns/ |
Breadcrumb Blog / DNS; the same, with search kept inside the topic and a "Search all posts" link |
/blog/page/2/ |
Breadcrumb Blog / Page 2 |
/blog/vpn-leaks/ |
Breadcrumb Blog / {first tag}; the article and its contents; your call to action; share links; the series; related posts |
The topic is in the path, which gives each topic a real page that search engines can
index. The search and date are in the query string, so they can be shared and Back
works. Switching topic keeps the search and date. The date menu lists each year with
posts, newest first, and its twelve months (empty months greyed out); picking one
filters the list in the browser, from search.json, so the menu needs search on and
shows once the explorer runs. The feed icon links RSS, else Atom, else JSON Feed.
A click on any link to one of the blog's feeds (the browse bar's icon, the
"Subscribe" link at the end of a list, or your own) opens a dialog instead of a page
of raw XML. Readers pick the format (RSS, Atom or JSON Feed, with a line on each),
copy its address, open it in their feed reader app (feed:), view the feed, or follow
"What is a feed?". The choice is remembered. Esc, the close button or a click outside
closes it, and focus goes back to the link. A click with a modifier key, or no
script, opens the feed as before. It's built with DOM calls, so a strict Content
Security Policy needs no change.
enhanceBlogPage() turns it on for blog pages (subscribe: false turns it off). For
the rest of your site, such as a header icon on every page, use the virtual module's
blog:
import "@binarynoir/vite-plugin-blog/subscribe.css"; // only the dialog; styles.css includes it
import { enhanceFeedLinks } from "@binarynoir/vite-plugin-blog/runtime";
import { blog } from "virtual:blog/latest";
if (blog) enhanceFeedLinks({ feeds: blog.feeds, title: blog.feedTitle, labels: blog.labels });openSubscribeDialog(options, format?) opens it from your own button.
The breadcrumb's "Blog" always goes to the plain index.
The build writes {base}search.json (BlogSearchIndex). It holds each listed post's
summary, its headings and up to search.text characters of its text, but no front
matter. Results rank title matches first, then tags, headings, the description, authors
and the text. Every word must match, either at the start of a word or, for less, inside
one. Accents and case don't matter.
search: { text: 3000, pageSize: 12 }, // or search: falseAt a few hundred posts the index stays at a few hundred KB, fetched once and only when
the field is used. For thousands of posts, set text: 0 (titles, descriptions and
headings only), or use Pagefind with data-pagefind-body, which the article already has.
import {
loadSearchIndex,
searchPosts,
sortPosts,
paginate,
readExplorerState,
writeExplorerState,
cardTree,
toHtml,
readBlogConfig,
} from "@binarynoir/vite-plugin-blog/runtime";
const config = readBlogConfig(); // the page's #blog-config JSON
const index = await loadSearchIndex(config!.searchUrl!);
const found = searchPosts(index.posts, "dns", index.tags).map((result) => result.post);
const { items } = paginate(sortPosts(found, "newest"), 1, 12);
list.innerHTML = items
.map((post) => toHtml(cardTree(post, { labels: config!.labels, tags: index.tags })))
.join("");cardTree, pagerTree, breadcrumbTree, searchFormTree and tagListTree return
element trees. They give the same markup the build writes, so React, Svelte or plain DOM
code can render them too.
Install vue (3.4 or later). The components render the same trees, so a card in search
results or on your home page matches the cards on the blog's own pages.
| Component / function | Props | Use |
|---|---|---|
BlogPostCard |
post, tags, labels, headingLevel, label, featured, cover |
One card |
BlogPostList |
posts, tags, labels, headingLevel, limit, cover |
A list of cards, such as a home page strip |
BlogPager |
page, pageCount, href, labels; emits navigate |
Numbered pages whose links also work without a script |
BlogExplorer |
config, staticSelector, resultsSelector, shortcut, browse |
Search, date filter, sort and pages for a list page, with the browse bar from config.browse. Press / to search, Esc to clear or close the date menu |
mountBlogExplorer() |
{ selector, config, setup } |
Mounts BlogExplorer on [data-blog-explorer], if the page has one, with the browse bar when the build wrote one there |
A home page strip:
<script setup lang="ts">
import "@binarynoir/vite-plugin-blog/styles.css";
import { BlogPostList } from "@binarynoir/vite-plugin-blog/vue";
import { blog, posts, tags } from "virtual:blog/latest";
</script>
<template>
<section v-if="posts.length">
<h2>From the blog</h2>
<BlogPostList :posts="posts" :tags="tags" :labels="blog.labels" :limit="3" />
<a :href="blog.indexUrl">All posts →</a>
</section>
</template>If some builds of your site leave the blog out, give those builds an empty
virtual:blog/latest (export const posts = []; export const tags = {}; export const blog = null;).
@binarynoir/vite-plugin-blog/styles.css styles everything above. Its rules have zero
specificity, so your own rules always win. To match your site, map its tokens:
:root {
--blog-text: var(--text);
--blog-muted: var(--text-secondary);
--blog-surface: var(--surface);
--blog-border: var(--border);
--blog-muted-bg: var(--subtle);
--blog-accent: var(--brand);
--blog-accent-tint: var(--brand-tint);
--blog-font-display: var(--font-heading);
--blog-radius: 16px;
}The full list is at the top of styles.css. Both themes follow, as long as your tokens
change with the theme.
npm install -D @binarynoir/vite-plugin-blog(andvuefor the components).- Add
blogPlugin({ dir, template, site, siteName, image })tovite.config.ts. - Write a page shell with
<!--blog:head-->and<!--blog:content-->. Its script importsvirtual:blog/code.cssand the styles, then callsenhanceBlogPage()andmountBlogExplorer(). - Map the
--blog-*tokens to your design system. - Add
"@binarynoir/vite-plugin-blog/client"totsconfig.jsontypes. - Optional: a home page strip from
virtual:blog/latest,feeds: { discovery: "site" }, andrender.article: (post, h) => h.renderArticle(post, { end: yourCallToAction }).
With site set, the build writes /blog/feed.xml (RSS 2.0), /blog/atom.xml and
/blog/feed.json (JSON Feed 1.1), each with the newest 20 listed posts and their whole
articles, plus /blog/sitemap.xml. Every blog page links the feeds from its <head>, and
renderFeedLinks() gives you the same tags for other pages. Dev serves them too.
feeds: { rss: true, atom: false, json: true, limit: 50, content: false, discovery: "site" },
sitemap: false,discovery: "site" links the feeds from every page's <head>, home page included, so
browsers and feed readers find them from anywhere on the site.
| Option | Default | What it does |
|---|---|---|
dir |
(required) | The content folder, relative to Vite's root or absolute |
template |
(required) | The page shell, relative to Vite's root |
base |
/blog/ |
Where the blog lives on the site |
site |
The site's origin. Canonical URLs, social cards, feeds and the sitemap need it | |
preview |
false |
Also build drafts and scheduled posts, with noindex |
now |
build time | What "now" is when deciding whether a post is scheduled |
timeZone |
UTC |
For dates without an offset, and for showing dates |
locale |
en-US |
For showing dates, and the feeds' language |
wordsPerMinute |
230 |
For reading time |
titleSuffix |
'' |
Added after a post's title in <title> |
siteName |
og:site_name, the publisher, and the end of list pages' titles |
|
image |
Share card for list pages and posts without a cover (path or URL) | |
index |
{ title: "Blog" } |
The index's { title, description, eyebrow } |
tagPages |
true |
Write a page per tag in use at {base}tag/{tag}/ |
pageSize |
0 |
Posts per list page; 0 puts them all on one |
feeds |
all three, with site |
{ rss, atom, json, limit, title, description, content }, or false |
sitemap |
true, with site |
{base}sitemap.xml |
search |
on | { text: 3000, pageSize: 12 }, or false |
latest |
6 |
Posts in virtual:blog/latest |
share |
six networks | { networks, mastodon }, or false. Needs site |
related |
3 |
Related posts at the end of a post; 0 for none |
announcements |
on | The banner's settings (above), or false |
labels |
English | The words the default markup writes (below) |
limits |
{ title: 70, description: 160, minTags: 0, maxTags } |
|
tags |
tags.yml |
The only tags allowed; without either, any tag is |
authors |
authors.yml |
Known authors, by id: { name, url, email } |
defaultAuthor |
An author id for posts that don't name one | |
directives |
Your own ::: directives (below) |
|
highlight |
GitHub themes | { themes: { light, dark }, classPrefix }, or false |
markdown |
(md) => void: add markdown-it plugins |
|
isKnownPath |
(path) => boolean: also check links to site pages outside the blog |
|
validate |
(post) => string[]: your own checks; messages fail the build |
|
render |
{ head, article, listHead, list }: replace the default markup (below) |
Translate or reword what the default markup writes. {n} and {count} are numbers.
labels: {
readingTime: "{n} Min. Lesezeit",
pageOf: "Seite {n} von {count}",
announcementCount: "{n} Ankündigungen",
dismiss: "Schließen",
},Every key, with its default, is in DEFAULT_LABELS (exported from the package and
from /runtime). Among them are tagDescription ("Posts about {tag}."), topic,
allPosts, search, searchTopic, sortNewest, results, noResults, share,
relatedPosts, series, seriesPart and subscribe. The Vue components get the same
labels through the page's #blog-config JSON, or through blog.labels from the virtual
modules.
A leaf directive is one line. A container wraps Markdown until a line holding
only :::, and can nest.
blogPlugin({
// ...
directives: {
tool: {
kind: "leaf",
render: ({ args, error, post }) => {
const [name, query] = args.split(/\s+/);
if (!name) error("needs a tool name");
return `<div class="tool" data-tool="${name}" data-q="${query ?? ""}"></div>`;
},
},
},
});::: tool check example.com
::: warning Before you start
Back up the zone file.
:::render.article and render.head get the post and a set of helpers. Most sites only
need to add something to the default article:
render: {
article: (post, h) => h.renderArticle(post, { end: `<aside class="cta">…</aside>` }),
},The helpers:
escapeHtml,formatDate,dateAttribute,labelandlabelsindexUrl,tagUrl(tag),announcementsUrl,searchUrl,siteName,usedTags(tags with a page) andtagInfoadjacent(post),related(post, limit),series(post),breadcrumbs(postOrPage)andsummary(post)posts(every listed post, newest first) andtags- pieces:
renderBreadcrumbs,renderCard,renderPager,renderShare,renderSeries,renderRelated,renderTopics,renderSearch,renderBrowse,renderExplorer(the search form and the browse bar, as list pages use),renderFeedList,renderClientConfig,renderTocandrenderFeedLinks - the defaults:
renderHead,renderArticle(post, { beforeBody, end }),renderListHeadandrenderList(page, { eyebrow, lead, end })
List pages get kind ("index", "tag" or "announcements"), url, canonical,
title, description, tag, their posts, and page, pageCount, pageUrls,
previousUrl and nextUrl.
If you write your own list markup, keep data-blog-explorer (the search form, and the
browse bar if you want it: renderExplorer(page) writes both),
data-blog-results (where results go) and data-blog-static (the list that results
replace) for the explorer, and renderClientConfig(page) for its settings.
Classes. Posts use blog-crumbs, blog-layout (has-toc), blog-post,
blog-post-head, blog-lead, blog-meta, blog-tags, blog-tag, blog-post-cover,
blog-toc, blog-toc-side, blog-toc-inline, blog-toc-title, blog-toc-2,
blog-toc-3, blog-prose, blog-post-end, blog-share, blog-share-link,
blog-share-copy, blog-series, blog-related and blog-post-nav. Lists use
blog-list, blog-list-head, blog-eyebrow, blog-explorer, blog-search,
blog-sort, blog-topics, blog-browse, blog-browse-topics, blog-browse-tabs,
blog-browse-tab, blog-browse-count, blog-browse-tools, blog-browse-feed,
blog-menu (is-active), blog-menu-button, blog-menu-panel, blog-menu-year,
blog-menu-months, blog-menu-choice (is-empty), blog-static, blog-results, blog-cards, blog-card
(is-featured, is-pinned), blog-card-cover, blog-card-body, blog-card-label,
blog-card-title, blog-card-description, blog-pager, blog-feeds and blog-empty.
Inside posts: heading-anchor, code-block, code-copy, callout, callout-note,
callout-tip, callout-warning and callout-title.
import { posts } from "virtual:blog/posts";
for (const post of posts.slice(0, 3)) console.log(post.title, post.url, post.date);Each listed post has slug, url, title, description, date, dateText and
dateTime (formatted in the blog's locale and time zone), updated, tags, authors
(names and links only), pinned, featured, series, cover, readingMinutes and
data (the front matter). The module also exports tags and blog.
virtual:blog/latest is the same, with only the newest latest posts.
Maintainers only. npm run release:patch (or minor, major) bumps the version, tags
and pushes. The tag runs .github/workflows/release.yml, which tests, builds and
publishes to npm with Trusted Publishing.
Blog for Vite is one of a family of open-source tools from BinaryNoir.
Pairs well with Blog for Vite
- Blog: posts anywhere, a main blog and section blogs, with RSS feeds
- Optimize Images: smaller images in the build output
- Image Fallback: a placeholder instead of a failed build
See them all: VitePress plugins, Vite plugins, editor extensions and command-line tools, with documentation and live demos, at binarynoir.tech.