@binarynoir/vitepress-blog 0.2.0 → 0.4.0

package/dist/vitepress.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/vitepress.ts
 var vitepress_exports = {};
 __export(vitepress_exports, {
+  attachAnnouncements: () => attachAnnouncements,
   blogHead: () => blogHead,
   blogMarkdown: () => blogMarkdown,
   blogPageData: () => blogPageData,
@@ -63,6 +64,11 @@ function hasAnyTag(post, tags) {
   const wanted = new Set(tags.map((tag) => tag.toLowerCase()));
   return post.post.tags.some((tag) => wanted.has(tag.toLowerCase()));
 }
+function inAnyCategory(post, categories) {
+  if (categories.length === 0) return true;
+  const category = post.post.category.toLowerCase();
+  return !!category && categories.some((wanted) => wanted.toLowerCase() === category);
+}
 function blogCoversPost(index, post, sections) {
   if (index.index.scope === "section") return isInFolders(post.relativePath, index.index.folders);
   if (!isInFolders(post.relativePath, index.index.folders)) return false;
@@ -76,22 +82,22 @@ function compareDates(a, b) {
 function compareByDate(a, b) {
   return compareDates(a.post.date, b.post.date) || a.post.title.localeCompare(b.post.title);
 }
-function pinStickyPosts(posts, limit) {
-  const sticky = posts.filter((post) => post.post.sticky);
-  const pinned = new Set(limit ? sticky.slice(0, limit) : sticky);
+function pinPosts(posts, limit) {
+  const candidates = posts.filter((post) => post.post.pinned);
+  const pinned = new Set(limit ? candidates.slice(0, limit) : candidates);
   return { pinned: [...pinned], rest: posts.filter((post) => !pinned.has(post)) };
 }
 function listBlogPosts(pages, index, options) {
   const sections = pages.filter(isIndex).filter((page) => page.index.scope === "section");
-  let posts = pages.filter(isPost).filter((post) => options.drafts || !post.post.draft).filter((post) => blogCoversPost(index, post, sections) && hasAnyTag(post, index.index.tags)).sort(compareByDate);
-  if (options.stickyFirst) {
-    const { pinned, rest } = pinStickyPosts(posts, index.index.stickyLimit);
+  let posts = pages.filter(isPost).filter((post) => options.drafts || !post.post.draft).filter((post) => blogCoversPost(index, post, sections) && hasAnyTag(post, index.index.tags)).filter((post) => inAnyCategory(post, index.index.categories)).sort(compareByDate);
+  if (options.pinnedFirst) {
+    const { pinned, rest } = pinPosts(posts, index.index.pinLimit);
     posts = [...pinned, ...rest];
   }
   return options.applyLimit && index.index.limit ? posts.slice(0, index.index.limit) : posts;
 }
 function findHomeBlog(pages, post, drafts) {
-  const listing = pages.filter(isIndex).filter((index) => listBlogPosts(pages, index, { drafts, stickyFirst: false, applyLimit: false }).includes(post));
+  const listing = pages.filter(isIndex).filter((index) => listBlogPosts(pages, index, { drafts, pinnedFirst: false, applyLimit: false }).includes(post));
   const sections = listing.filter((index) => index.index.scope === "section");
   if (sections.length) return deepestFirst(sections, post.relativePath)[0];
   return listing[0] ?? null;
@@ -110,9 +116,120 @@ function findBlogForPage(pages, relativePath) {
 }
 function findBlogsListing(pages, post) {
   return pages.filter(isIndex).filter(
-    (index) => listBlogPosts(pages, index, { drafts: false, stickyFirst: false, applyLimit: false }).includes(post)
+    (index) => listBlogPosts(pages, index, { drafts: false, pinnedFirst: false, applyLimit: false }).includes(post)
   );
 }
+function listAnnouncements(pages, drafts) {
+  return pages.filter(isPost).filter((post) => post.post.announcement && (drafts || !post.post.draft)).sort(compareByDate);
+}
+function findAnnouncementBlog(pages, announcements, drafts) {
+  if (announcements.length === 0) return null;
+  const listingAll = pages.filter(isIndex).filter((index) => {
+    const listed = listBlogPosts(pages, index, { drafts, pinnedFirst: false, applyLimit: false });
+    return announcements.every((post) => listed.includes(post));
+  });
+  return listingAll.find((index) => index.index.scope === "site") ?? listingAll[0] ?? findHomeBlog(pages, announcements[0], drafts);
+}
+
+// src/types.ts
+var DEFAULT_LABELS = {
+  by: "By",
+  published: "Published",
+  updated: "Updated",
+  dateTime: "{date} at {time}",
+  readingTime: "{n} min read",
+  newer: "Newer post",
+  older: "Older post",
+  allPosts: "All posts in {blog}",
+  draft: "Draft",
+  pinned: "Pinned",
+  announcement: "Announcement",
+  announcements: "Announcements",
+  announcementCount: "{n} announcements",
+  dismiss: "Dismiss",
+  noPosts: "No posts yet.",
+  undated: "Undated",
+  browse: "Browse posts",
+  categories: "Categories",
+  tags: "Keywords",
+  archive: "Archive",
+  category: "Category",
+  tag: "Keyword",
+  postCount: "{n} posts",
+  postCountOne: "{n} post",
+  noMatches: "No posts match these filters.",
+  removeFilter: "Remove filter: {filter}",
+  showAll: "Show all posts",
+  previous: "Previous",
+  next: "Next",
+  pages: "Pages",
+  subscribe: "Subscribe",
+  rssFeed: "RSS feed for {blog}"
+};
+
+// src/util.ts
+var HTML_ESCAPES = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+function escapeHtml(value) {
+  return value.replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
+}
+function escapeMarkdown(text) {
+  const escaped = text.replace(/[\\`*_[\]#|~]/g, "\\$&").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return /[{}]/.test(escaped) ? `<span v-pre>${escaped}</span>` : escaped;
+}
+function escapeTemplateText(text) {
+  const escaped = escapeHtml(text);
+  return /[{}]/.test(escaped) ? `<span v-pre>${escaped}</span>` : escaped;
+}
+function isExternalUrl(url) {
+  return /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(url);
+}
+function toMarkdownUrl(url) {
+  return encodeURI(url).replace(/[()]/g, (character) => character === "(" ? "%28" : "%29");
+}
+function toPageLink(text, routePath) {
+  return `[${escapeMarkdown(text)}](${toMarkdownUrl(`/${routePath}`)})`;
+}
+function toUrlPath(routePath, cleanUrls) {
+  return `/${routePath.replace(/(^|\/)index\.md$/, "$1").replace(/\.md$/, cleanUrls ? "" : ".html")}`;
+}
+function joinUrl(base, urlPath) {
+  return `${base.replace(/\/+$/, "")}/${urlPath.replace(/^\/+/, "")}`;
+}
+var ANNOUNCEMENTS_KEY = "blogAnnouncements";
+var DISMISSED_STORAGE_KEY = "vp-blog-announcements-dismissed";
+var DISMISSED_CLASS = "vp-blog-announcement-dismissed";
+
+// src/announcements.ts
+function resolveAnnouncements(pages, options, cleanUrls) {
+  const drafts = options.drafts ?? false;
+  const announcements = listAnnouncements(pages, drafts);
+  if (announcements.length === 0) return null;
+  const blog = findAnnouncementBlog(pages, announcements, drafts);
+  const labels = { ...DEFAULT_LABELS, ...options.labels };
+  return {
+    items: announcements.map((post) => ({
+      id: `${post.routePath}@${post.post.date?.toISOString() ?? ""}`,
+      text: post.post.announcementText || post.post.title,
+      link: toUrlPath(post.routePath, cleanUrls)
+    })),
+    listLink: blog ? `${toUrlPath(blog.routePath, cleanUrls)}?announcements` : "",
+    labels: {
+      announcement: labels.announcement,
+      announcementCount: labels.announcementCount,
+      dismiss: labels.dismiss
+    }
+  };
+}
+function renderDismissedScript(data) {
+  const id = JSON.stringify(data.items[0].id).replace(/</g, "\\u003c");
+  return `try{var d=JSON.parse(localStorage.getItem(${JSON.stringify(DISMISSED_STORAGE_KEY)})||'[]');if(Array.isArray(d)&&d.indexOf(${id})>-1)document.documentElement.classList.add(${JSON.stringify(DISMISSED_CLASS)})}catch(e){}`;
+}
 
 // src/frontmatter.ts
 var import_node_path = __toESM(require("path"), 1);
@@ -213,6 +330,13 @@ function toDateTimeAttribute({ date, hasTime }, timeZone) {
 function yearIn(date, timeZone) {
   return Number(toZonedIsoDate(date, timeZone).slice(0, 4));
 }
+function monthIn(date, timeZone) {
+  return toZonedIsoDate(date, timeZone).slice(0, 7);
+}
+function formatMonth(month, locale, format) {
+  const [year, number] = month.split("-").map(Number);
+  return new Intl.DateTimeFormat(locale, { timeZone: "UTC", ...format }).format(Date.UTC(year, number - 1, 1, 12));
+}
 
 // src/frontmatter.ts
 var POST_FRONTMATTER_KEY = "blog";
@@ -320,6 +444,7 @@ function resolvePostData(data, content, fallbackTitle, options = {}) {
   const timeZone = resolveTimeZone(options.timeZone);
   const date = parsePostDate(pick("date"), timeZone);
   const updated = parsePostDate(pick("updated"), timeZone);
+  const announcementText = typeof post.announcement === "string" ? clean(post.announcement.trim()) : "";
   return {
     title: clean(toText(post.title) || toText(data.title) || readHeading(content)) || fallbackTitle,
     summary: clean(toText(post.summary) || toText(data.description) || readExcerpt(content)),
@@ -335,8 +460,11 @@ function resolvePostData(data, content, fallbackTitle, options = {}) {
     tags: toStringList(pick("tags")),
     category: toText(pick("category")),
     scope: toScope(post.scope),
-    sticky: post.sticky === true,
+    // `sticky` is this setting's old name.
+    pinned: (post.pinned ?? post.sticky) === true,
     draft: post.draft === true,
+    announcement: post.announcement === true || !!announcementText,
+    announcementText,
     byline: toBoolean(post.byline),
     cover: toBoolean(post.cover),
     postNav: toBoolean(post.postNav),
@@ -346,6 +474,9 @@ function resolvePostData(data, content, fallbackTitle, options = {}) {
 function toLayout(value) {
   return value === "grid" || value === "compact" ? value : "list";
 }
+function toGroupBy(value) {
+  return value === "year" || value === "month" ? value : "";
+}
 function defaultFeedPath(relativePath) {
   const name = import_node_path.default.posix.basename(relativePath, ".md");
   return name === "index" ? "feed.xml" : `${name}-feed.xml`;
@@ -379,13 +510,17 @@ function resolveIndexConfig(data, relativePath, defaults = {}) {
     scope,
     folders: folders.length ? resolveFolders(folders, relativePath) : scope === "section" ? [ownFolder] : [],
     tags: toStringList(options.tags),
+    categories: toStringList(options.categories),
     limit: typeof options.limit === "number" && options.limit > 0 ? Math.floor(options.limit) : 0,
     layout: toLayout(options.layout),
-    groupByYear: options.groupBy === "year",
+    groupBy: toGroupBy(options.groupBy),
     showTags: options.showTags !== false,
+    showCategory: options.showCategory !== false,
+    categoryList: options.categoryList !== false,
     tagList: options.tagList !== false,
+    archive: options.archive !== false,
     pageSize: toCount(options.pageSize, toCount(defaults.pageSize, 10)),
-    stickyLimit: toCount(options.stickyLimit, toCount(defaults.stickyLimit, 0)),
+    pinLimit: toCount(options.pinLimit ?? options.stickyLimit, toCount(defaults.pinLimit ?? defaults.stickyLimit, 0)),
     rssLink: typeof options.rssLink === "boolean" ? options.rssLink : defaults.rssLink ?? true,
     feed: toFeed(options.feed, relativePath)
   };
@@ -395,43 +530,6 @@ function resolveIndexConfig(data, relativePath, defaults = {}) {
 var import_node_crypto = require("crypto");
 var import_node_fs = require("fs");
 var import_node_path2 = __toESM(require("path"), 1);
-
-// src/util.ts
-var HTML_ESCAPES = {
-  "&": "&amp;",
-  "<": "&lt;",
-  ">": "&gt;",
-  '"': "&quot;",
-  "'": "&#39;"
-};
-function escapeHtml(value) {
-  return value.replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
-}
-function escapeMarkdown(text) {
-  const escaped = text.replace(/[\\`*_[\]#|~]/g, "\\$&").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-  return /[{}]/.test(escaped) ? `<span v-pre>${escaped}</span>` : escaped;
-}
-function escapeTemplateText(text) {
-  const escaped = escapeHtml(text);
-  return /[{}]/.test(escaped) ? `<span v-pre>${escaped}</span>` : escaped;
-}
-function isExternalUrl(url) {
-  return /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(url);
-}
-function toMarkdownUrl(url) {
-  return encodeURI(url).replace(/[()]/g, (character) => character === "(" ? "%28" : "%29");
-}
-function toPageLink(text, routePath) {
-  return `[${escapeMarkdown(text)}](${toMarkdownUrl(`/${routePath}`)})`;
-}
-function toUrlPath(routePath, cleanUrls) {
-  return `/${routePath.replace(/(^|\/)index\.md$/, "$1").replace(/\.md$/, cleanUrls ? "" : ".html")}`;
-}
-function joinUrl(base, urlPath) {
-  return `${base.replace(/\/+$/, "")}/${urlPath.replace(/^\/+/, "")}`;
-}
-
-// src/feed.ts
 function toAbsoluteUrl(urlPath, site) {
   return joinUrl(site.siteUrl, joinUrl(site.base, urlPath));
 }
@@ -527,33 +625,6 @@ var import_node_path6 = __toESM(require("path"), 1);
 
 // src/render.ts
 var import_node_path3 = __toESM(require("path"), 1);
-
-// src/types.ts
-var DEFAULT_LABELS = {
-  by: "By",
-  published: "Published",
-  updated: "Updated",
-  dateTime: "{date} at {time}",
-  readingTime: "{n} min read",
-  newer: "Newer post",
-  older: "Older post",
-  allPosts: "All posts in {blog}",
-  draft: "Draft",
-  sticky: "Pinned",
-  noPosts: "No posts yet.",
-  undated: "Undated",
-  tags: "Keywords",
-  tagged: "Posts tagged {tag}",
-  showAll: "Show all posts",
-  noTagged: "No posts tagged {tag}.",
-  previous: "Previous",
-  next: "Next",
-  pages: "Pages",
-  subscribe: "Subscribe",
-  rssFeed: "RSS feed for {blog}"
-};
-
-// src/render.ts
 var BLOG_POSTS_PLACEHOLDER = "<!-- blog-posts -->";
 function createRenderContext(options, pageDirectory, feeds = !!options.siteUrl) {
   const locale = options.locale ?? "en-US";
@@ -607,25 +678,41 @@ function renderAuthors(authors, context) {
 function renderBadge(kind, context) {
   return `<span class="vp-blog-badge vp-blog-badge--${kind}">${escapeTemplateText(context.labels[kind])}</span>`;
 }
-function toTagUrl(blogRoutePath, tag) {
-  const value = encodeURIComponent(tag.toLowerCase()).replace(/[()]/g, (c) => c === "(" ? "%28" : "%29");
+function toFilterUrl(blogRoutePath, param, value) {
+  const encoded = encodeURIComponent(value.toLowerCase()).replace(/[()]/g, (c) => c === "(" ? "%28" : "%29");
   const page = blogRoutePath.replace(/(^|\/)index\.md$/, "$1");
-  return `${toMarkdownUrl(`/${page}`)}?tag=${value}`;
+  return `${toMarkdownUrl(`/${page}`)}?${param}=${encoded}`;
+}
+function renderFilterLink(text, param, blogRoutePath, className) {
+  return blogRoutePath ? `[${escapeMarkdown(text)}](${toFilterUrl(blogRoutePath, param, text)})` : `<span class="${className}">${escapeTemplateText(text)}</span>`;
 }
 function renderTags(tags, blogRoutePath) {
-  return tags.map(
-    (tag) => blogRoutePath ? `[${escapeMarkdown(tag)}](${toTagUrl(blogRoutePath, tag)})` : `<span class="vp-blog-tag">${escapeTemplateText(tag)}</span>`
-  ).join(" ");
+  return tags.map((tag) => renderFilterLink(tag, "tag", blogRoutePath, "vp-blog-tag")).join(" ");
 }
 function toTagsAttribute(post) {
   return escapeHtml(post.post.tags.map((tag) => tag.toLowerCase()).join("|"));
 }
+function toItemAttributes(post, context) {
+  const { category, date, announcement } = post.post;
+  const attributes = [`data-vp-blog-item data-tags="${toTagsAttribute(post)}"`];
+  if (category) attributes.push(`data-category="${escapeHtml(category.toLowerCase())}"`);
+  if (date) attributes.push(`data-month="${monthIn(date, context.dates.timeZone)}"`);
+  if (announcement) attributes.push("data-announcement");
+  return attributes.join(" ");
+}
+function renderBadges(post, context) {
+  const { draft, pinned, announcement } = post.post;
+  return [
+    draft && renderBadge("draft", context),
+    pinned && renderBadge("pinned", context),
+    announcement && renderBadge("announcement", context)
+  ].filter(Boolean).join(" ");
+}
 function renderMeta(post, context, include) {
-  const { date, dateHasTime, updated, updatedHasTime, readingMinutes, authors, draft, sticky } = post.post;
+  const { date, dateHasTime, updated, updatedHasTime, readingMinutes, authors } = post.post;
   const parts = [];
   if (include.badges) {
-    const badges = [draft && renderBadge("draft", context), sticky && renderBadge("sticky", context)];
-    const shown = badges.filter(Boolean).join(" ");
+    const shown = renderBadges(post, context);
     if (shown) parts.push(shown);
   }
   if (date) {
@@ -652,16 +739,18 @@ function renderCard(post, context, index) {
   const link = `/${post.routePath}`;
   const image = toImageSource(post, context.pageDirectory);
   const modifiers = [
-    post.post.sticky && "sticky",
+    post.post.pinned && "pinned",
     post.post.draft && "draft",
+    post.post.announcement && "announcement",
     image && "with-image",
     image && post.post.imageFit === "contain" && "contain"
   ].filter(Boolean).map((modifier) => ` vp-blog-card--${modifier}`).join("");
   const alt = escapeMarkdown(post.post.imageAlt);
   return [
-    `<article class="vp-blog-card${modifiers}"${imageStyle(post)} data-vp-blog-item data-tags="${toTagsAttribute(post)}">`,
+    `<article class="vp-blog-card${modifiers}"${imageStyle(post)} ${toItemAttributes(post, context)}>`,
     ...image ? block("vp-blog-card__image", `[![${alt}](${toMarkdownUrl(image)})](${toMarkdownUrl(link)})`) : [],
     '<div class="vp-blog-card__body">',
+    ...index.index.showCategory && post.post.category ? block("vp-blog-card__category", renderFilterLink(post.post.category, "category", index.routePath, "")) : [],
     ...block("vp-blog-card__title", toPageLink(post.post.title, post.routePath)),
     ...block("vp-blog-card__meta", renderMeta(post, context, { authors: true, updated: false, badges: true })),
     ...block("vp-blog-card__summary", escapeMarkdown(post.post.summary)),
@@ -672,8 +761,8 @@ function renderCard(post, context, index) {
 }
 function renderCompactItem(post, context) {
   const date = post.post.date ? `${renderTime(post.post.date, post.post.dateHasTime, context)} ` : "";
-  const badges = [post.post.draft && renderBadge("draft", context), post.post.sticky && renderBadge("sticky", context)].filter(Boolean).join(" ");
-  const marker = `<span hidden data-vp-blog-item data-tags="${toTagsAttribute(post)}"></span>`;
+  const badges = renderBadges(post, context);
+  const marker = `<span hidden ${toItemAttributes(post, context)}></span>`;
   return `- ${marker}${date}${toPageLink(post.post.title, post.routePath)}${badges ? ` ${badges}` : ""}`;
 }
 function renderGroup(posts, index, context) {
@@ -693,18 +782,23 @@ function renderGroup(posts, index, context) {
     "</div>"
   ];
 }
-function renderYears(posts, index, context) {
-  const years = /* @__PURE__ */ new Map();
+function renderGroups(posts, index, context) {
+  const { groupBy } = index.index;
+  if (!groupBy) return renderGroup(posts, index, context);
+  const { timeZone, locale } = context.dates;
+  const groups = /* @__PURE__ */ new Map();
   for (const post of posts) {
-    const year = post.post.date ? String(yearIn(post.post.date, context.dates.timeZone)) : context.labels.undated;
-    years.set(year, [...years.get(year) ?? [], post]);
+    const { date } = post.post;
+    const key = !date ? "" : groupBy === "year" ? String(yearIn(date, timeZone)) : monthIn(date, timeZone);
+    groups.set(key, [...groups.get(key) ?? [], post]);
   }
   const lines = [];
-  for (const [year, group] of years) {
+  for (const [key, group] of groups) {
+    const heading = !key ? context.labels.undated : groupBy === "year" ? key : formatMonth(key, locale, { month: "long", year: "numeric" });
     lines.push(
-      '<section class="vp-blog-year">',
+      `<section class="vp-blog-group vp-blog-${groupBy}">`,
       "",
-      `## ${escapeMarkdown(year)}`,
+      `## ${escapeMarkdown(heading)}`,
       "",
       ...renderGroup(group, index, context),
       "",
@@ -713,42 +807,114 @@ function renderYears(posts, index, context) {
   }
   return lines;
 }
-function collectTags(posts) {
-  const tags = /* @__PURE__ */ new Map();
+function collectValues(posts, pick) {
+  const values = /* @__PURE__ */ new Map();
   for (const post of posts) {
-    for (const tag of new Set(post.post.tags)) {
-      const entry = tags.get(tag.toLowerCase()) ?? { tag, count: 0 };
+    for (const value of new Set(pick(post))) {
+      const entry = values.get(value.toLowerCase()) ?? { value, count: 0 };
       entry.count++;
-      tags.set(tag.toLowerCase(), entry);
+      values.set(value.toLowerCase(), entry);
     }
   }
-  return [...tags.values()].sort((a, b) => a.tag.localeCompare(b.tag, void 0, { sensitivity: "base" }));
+  return [...values.values()].sort((a, b) => a.value.localeCompare(b.value, void 0, { sensitivity: "base" }));
 }
-function renderTagList(posts, index, context) {
-  const tags = collectTags(posts);
-  if (!index.index.tagList || tags.length === 0) return [];
-  const links = tags.map(
-    ({ tag, count }) => `[${escapeMarkdown(tag)} <span class="vp-blog-tags__count">${count}</span>](${toTagUrl(index.routePath, tag)})`
-  );
-  const label = `<span class="vp-blog-tags__label">${escapeTemplateText(context.labels.tags)}</span>`;
+function collectTags(posts) {
+  return collectValues(posts, (post) => post.post.tags).map(({ value, count }) => ({ tag: value, count }));
+}
+function collectCategories(posts) {
+  return collectValues(posts, (post) => post.post.category ? [post.post.category] : []);
+}
+function collectArchive(posts, timeZone) {
+  const years = /* @__PURE__ */ new Map();
+  for (const post of posts) {
+    if (!post.post.date) continue;
+    const month = monthIn(post.post.date, timeZone);
+    const year = years.get(month.slice(0, 4)) ?? { value: month.slice(0, 4), count: 0, months: [] };
+    year.count++;
+    const entry = year.months.find((candidate) => candidate.value === month);
+    if (entry) entry.count++;
+    else year.months.push({ value: month, count: 1 });
+    years.set(year.value, year);
+  }
+  const newestFirst = (a, b) => b.value.localeCompare(a.value);
+  return [...years.values()].sort(newestFirst).map((year) => ({ ...year, months: [...year.months].sort(newestFirst) }));
+}
+function renderChip(name, count, url, title = "") {
+  const tooltip = title ? ` "${title.replace(/"/g, "&quot;")}"` : "";
+  return `[<span class="vp-blog-facet__name">${escapeMarkdown(name)}</span> <span class="vp-blog-facet__count">${count}</span>](${url}${tooltip})`;
+}
+function renderFacet(facet, label, chips, ariaLabel = label, attributes = "") {
   return [
-    `<nav class="vp-blog-tags" aria-label="${escapeHtml(context.labels.tags)}">`,
+    `<div class="vp-blog-facet vp-blog-facet--${facet}" role="group" aria-label="${escapeHtml(ariaLabel)}" data-vp-blog-facet="${facet}"${attributes}>`,
+    `<span class="vp-blog-facet__label" aria-hidden="true">${escapeTemplateText(label)}</span>`,
+    '<div class="vp-blog-facet__chips">',
     "",
-    `${label} ${links.join(" ")}`,
+    chips.join(" "),
     "",
-    "</nav>"
+    "</div>",
+    "</div>"
   ];
 }
+function renderBrowse(posts, index, context) {
+  const { labels } = context;
+  const { locale, timeZone } = context.dates;
+  const blog = index.routePath;
+  const rows = [];
+  const categories = index.index.categoryList ? collectCategories(posts) : [];
+  if (categories.length) {
+    const chips = categories.map(({ value, count }) => renderChip(value, count, toFilterUrl(blog, "category", value)));
+    rows.push(...renderFacet("category", labels.categories, chips));
+  }
+  const tags = index.index.tagList ? collectTags(posts) : [];
+  if (tags.length) {
+    const chips = tags.map(({ tag, count }) => renderChip(tag, count, toFilterUrl(blog, "tag", tag)));
+    rows.push(...renderFacet("tag", labels.tags, chips));
+  }
+  const archive = index.index.archive ? collectArchive(posts, timeZone) : [];
+  if (archive.reduce((months, year) => months + year.months.length, 0) > 1) {
+    const years = archive.map(({ value, count }) => renderChip(value, count, toFilterUrl(blog, "year", value)));
+    rows.push(...renderFacet("year", labels.archive, years));
+    for (const year of archive) {
+      const months = year.months.map(
+        ({ value, count }) => renderChip(
+          formatMonth(value, locale, { month: "short" }),
+          count,
+          toFilterUrl(blog, "month", value),
+          formatMonth(value, locale, { month: "long", year: "numeric" })
+        )
+      );
+      const shown = archive.length === 1 ? "" : " hidden";
+      rows.push(
+        ...renderFacet(
+          "month",
+          year.value,
+          months,
+          `${labels.archive} ${year.value}`,
+          ` data-year="${year.value}"${shown}`
+        )
+      );
+    }
+  }
+  if (rows.length === 0) return [];
+  return [`<nav class="vp-blog-browse" aria-label="${escapeHtml(labels.browse)}">`, ...rows, "</nav>"];
+}
 function renderClientAttributes(index, context) {
   const { labels } = context;
   const attributes = {
     "data-page-size": String(index.index.pageSize),
-    "data-label-tagged": labels.tagged,
+    // For writing a `?month=` filter's name: "October 2026".
+    "data-locale": context.locale,
     "data-label-show-all": labels.showAll,
-    "data-label-no-tagged": labels.noTagged,
     "data-label-previous": labels.previous,
     "data-label-next": labels.next,
-    "data-label-pages": labels.pages
+    "data-label-pages": labels.pages,
+    "data-label-announcements": labels.announcements,
+    "data-label-category": labels.category,
+    "data-label-tag": labels.tag,
+    "data-label-post-count": labels.postCount,
+    "data-label-post-count-one": labels.postCountOne,
+    "data-label-no-matches": labels.noMatches,
+    "data-label-remove-filter": labels.removeFilter
   };
   return Object.entries(attributes).map(([name, value]) => `${name}="${escapeHtml(value)}"`).join(" ");
 }
@@ -759,17 +925,16 @@ function renderPostList(pinned, rest, index, context) {
   const lines = [
     `<div class="vp-blog" data-vp-blog ${renderClientAttributes(index, context)}>`,
     ...block("vp-blog-subscribe", renderRssLink(index, context)),
-    ...renderTagList(all, index, context),
-    '<div class="vp-blog-filter" data-vp-blog-filter hidden></div>'
+    ...renderBrowse(all, index, context),
+    '<div class="vp-blog-filter" data-vp-blog-filter role="status" hidden></div>'
   ];
   if (pinned.length)
     lines.push(
-      '<section class="vp-blog-sticky" data-vp-blog-sticky>',
+      '<section class="vp-blog-pinned" data-vp-blog-pinned>',
       ...renderGroup(pinned, index, context),
       "</section>"
     );
-  if (rest.length)
-    lines.push(...index.index.groupByYear ? renderYears(rest, index, context) : renderGroup(rest, index, context));
+  if (rest.length) lines.push(...renderGroups(rest, index, context));
   lines.push(`<nav class="vp-blog-pagination" data-vp-blog-pagination hidden></nav>`, "</div>");
   return `${lines.join("\n")}
 `;
@@ -778,8 +943,12 @@ function renderPostHeader(post, context, show, blogRoutePath = null) {
   const lines = [];
   if (show.byline) {
     const meta = renderMeta(post, context, { authors: true, updated: true, badges: true });
-    const tags = post.post.tags.length ? `<span class="vp-blog-byline__tags">${renderTags(post.post.tags, blogRoutePath)}</span>` : "";
-    lines.push(...block("vp-blog-byline", [meta, tags].filter(Boolean).join("\n\n")));
+    const { category, tags } = post.post;
+    const chips = [
+      category && `<span class="vp-blog-byline__category">${renderFilterLink(category, "category", blogRoutePath, "vp-blog-category")}</span>`,
+      tags.length && `<span class="vp-blog-byline__tags">${renderTags(tags, blogRoutePath)}</span>`
+    ].filter(Boolean).join(" ");
+    lines.push(...block("vp-blog-byline", [meta, chips].filter(Boolean).join("\n\n")));
   }
   if (show.cover && post.post.image) {
     const image = /^[./@~]/.test(post.post.image) || isExternalUrl(post.post.image) ? post.post.image : `./${post.post.image}`;
@@ -870,7 +1039,7 @@ function toOptionsKey(options) {
     options.wordsPerMinute,
     options.stripTags,
     options.pageSize,
-    options.stickyLimit,
+    options.pinLimit ?? options.stickyLimit,
     options.rssLink,
     options.timeZone
   ]);
@@ -959,10 +1128,13 @@ function resolveWidgetConfig(body) {
     config: {
       blog: typeof data.blog === "string" ? data.blog.trim() : "",
       limit: toCount2(data.limit) ?? DEFAULT_LIMIT,
-      stickyLimit: toCount2(data.stickyLimit),
+      // `stickyLimit` is this setting's old name.
+      pinLimit: toCount2(data.pinLimit ?? data.stickyLimit),
       layout,
       showTags: typeof data.showTags === "boolean" ? data.showTags : void 0,
+      showCategory: typeof data.showCategory === "boolean" ? data.showCategory : void 0,
       tags: toStringList(data.tags),
+      categories: toStringList(data.categories),
       more: data.more === false ? null : typeof data.more === "string" && data.more.trim() ? data.more.trim() : "",
       rssLink: typeof data.rssLink === "boolean" ? data.rssLink : void 0
     },
@@ -978,19 +1150,19 @@ function renderWidget(body, environment) {
     warn(config.blog ? `no blog page found at "${config.blog}"` : 'no blog covers this page: name one with "blog:"');
     return "";
   }
-  const stickyLimit = config.stickyLimit ?? blog.index.stickyLimit;
-  const wanted = new Set(config.tags.map((tag) => tag.toLowerCase()));
-  const posts = listBlogPosts(pages, blog, { drafts, stickyFirst: false, applyLimit: false }).filter(
-    (post) => wanted.size === 0 || post.post.tags.some((tag) => wanted.has(tag.toLowerCase()))
+  const pinLimit = config.pinLimit ?? blog.index.pinLimit;
+  const posts = listBlogPosts(pages, blog, { drafts, pinnedFirst: false, applyLimit: false }).filter(
+    (post) => hasAnyTag(post, config.tags) && inAnyCategory(post, config.categories)
   );
-  const { pinned, rest } = pinStickyPosts(posts, stickyLimit);
+  const { pinned, rest } = pinPosts(posts, pinLimit);
   const shown = [...pinned, ...rest].slice(0, config.limit || void 0);
   const view = {
     ...blog,
     index: {
       ...blog.index,
       layout: config.layout ?? blog.index.layout,
-      showTags: config.showTags ?? blog.index.showTags
+      showTags: config.showTags ?? blog.index.showTags,
+      showCategory: config.showCategory ?? blog.index.showCategory
     }
   };
   const lines = [`<div class="vp-blog-widget">`];
@@ -1063,8 +1235,8 @@ function hasFeeds(options) {
 }
 function withPostList(source, page, pages, options) {
   if (!isIndex(page)) return source;
-  const posts = listBlogPosts(pages, page, { drafts: options.drafts ?? false, stickyFirst: true, applyLimit: true });
-  const { pinned, rest } = pinStickyPosts(posts, page.index.stickyLimit);
+  const posts = listBlogPosts(pages, page, { drafts: options.drafts ?? false, pinnedFirst: true, applyLimit: true });
+  const { pinned, rest } = pinPosts(posts, page.index.pinLimit);
   const context = createRenderContext(options, import_node_path6.default.dirname(page.absolutePath), hasFeeds(options));
   const generated = renderPostList(pinned, rest, page, context);
   return source.includes(BLOG_POSTS_PLACEHOLDER) ? source.replace(BLOG_POSTS_PLACEHOLDER, () => `
@@ -1087,7 +1259,7 @@ function withPostDecorations(source, page, pages, options) {
   let result = header ? insertAfterTitle(source, header) : source;
   if (page.post.postNav ?? options.postNav ?? true) {
     if (blog) {
-      const posts = listBlogPosts(pages, blog, { drafts, stickyFirst: false, applyLimit: false });
+      const posts = listBlogPosts(pages, blog, { drafts, pinnedFirst: false, applyLimit: false });
       result = `${result.replace(/\s*$/, "")}
 
 ${renderPostNav(page, posts, blog, context)}
@@ -1135,6 +1307,9 @@ function blogMarkdown(md, options = {}) {
 
 // src/vitepress.ts
 var DEFAULT_FEED_LIMIT = 20;
+var PACKAGE_NAME = "@binarynoir/vitepress-blog";
+var SITE_DATA_MODULE = "/@siteData";
+var SCRIPT_MARKER = "data-vp-blog-announcement";
 function resolveSiteLocation(siteConfig, options) {
   const siteUrl = options.siteUrl ?? siteConfig.userConfig?.sitemap?.hostname ?? siteConfig.sitemap?.hostname;
   if (!siteUrl) return null;
@@ -1149,9 +1324,19 @@ function resolveSiteLocation(siteConfig, options) {
 function loadPages(siteConfig, options) {
   return loadBlogPages(siteConfig.srcDir, options, siteConfig);
 }
+function attachAnnouncements(siteConfig, options = {}) {
+  const site = siteConfig.site;
+  const data = resolveAnnouncements(loadPages(siteConfig, options), options, !!siteConfig.cleanUrls);
+  const changed = JSON.stringify(site[ANNOUNCEMENTS_KEY] ?? null) !== JSON.stringify(data);
+  if (data) site[ANNOUNCEMENTS_KEY] = data;
+  else delete site[ANNOUNCEMENTS_KEY];
+  site.head = (site.head ?? []).filter(([, attributes]) => !(SCRIPT_MARKER in (attributes ?? {})));
+  if (data) site.head.push(["script", { [SCRIPT_MARKER]: "" }, renderDismissedScript(data)]);
+  return changed;
+}
 function listFeedPosts(pages, index, options) {
   const limit = index.index.feed?.limit ?? options.feedLimit ?? DEFAULT_FEED_LIMIT;
-  return listBlogPosts(pages, index, { drafts: false, stickyFirst: false, applyLimit: false }).slice(0, limit);
+  return listBlogPosts(pages, index, { drafts: false, pinnedFirst: false, applyLimit: false }).slice(0, limit);
 }
 function renderIndexFeed(pages, index, site, siteConfig, options) {
   return renderFeed({
@@ -1253,11 +1438,26 @@ function blogVitePlugin(options = {}) {
   let siteConfig;
   const currentPages = () => siteConfig ? loadPages(siteConfig, options) : [];
   const dependentFiles = () => [...currentPages().map((page) => page.absolutePath), ...widgetPages];
+  const invalidate = (server, files) => {
+    for (const file of files) {
+      for (const module2 of server.moduleGraph.getModulesByFile(file) ?? []) server.moduleGraph.invalidateModule(module2);
+    }
+  };
+  const refreshAnnouncements = (server) => {
+    if (!siteConfig || !attachAnnouncements(siteConfig, options)) return false;
+    const module2 = server.moduleGraph.getModuleById(SITE_DATA_MODULE);
+    if (module2) server.moduleGraph.invalidateModule(module2);
+    return true;
+  };
   return {
     name: "vitepress-blog",
     enforce: "pre",
+    config() {
+      return { ssr: { noExternal: [PACKAGE_NAME] } };
+    },
     configResolved(config) {
       siteConfig = config.vitepress;
+      if (siteConfig) attachAnnouncements(siteConfig, options);
     },
     transform(code, id) {
       if (!siteConfig || !id.endsWith(".md") || !(mayHaveBlogFrontmatter(code) || hasWidget(code))) return null;
@@ -1268,11 +1468,8 @@ function blogVitePlugin(options = {}) {
     configureServer(server) {
       const refresh = (file) => {
         if (!siteConfig || !file.endsWith(".md")) return;
-        for (const dependent of dependentFiles()) {
-          for (const module2 of server.moduleGraph.getModulesByFile(dependent) ?? []) {
-            server.moduleGraph.invalidateModule(module2);
-          }
-        }
+        invalidate(server, dependentFiles());
+        refreshAnnouncements(server);
         server.ws.send({ type: "full-reload" });
       };
       server.watcher.on("add", refresh).on("unlink", refresh);
@@ -1303,6 +1500,11 @@ function blogVitePlugin(options = {}) {
     },
     handleHotUpdate({ file, modules, server }) {
       if (!siteConfig || !file.endsWith(".md")) return;
+      if (refreshAnnouncements(server)) {
+        invalidate(server, dependentFiles());
+        server.ws.send({ type: "full-reload" });
+        return [];
+      }
       const pages = currentPages();
       if (!pages.some((page) => page.absolutePath === file)) return;
       const affected = dependentFiles().filter((dependent) => dependent !== file).flatMap((dependent) => [...server.moduleGraph.getModulesByFile(dependent) ?? []]);
@@ -1339,6 +1541,7 @@ function withBlog(config, options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  attachAnnouncements,
   blogHead,
   blogMarkdown,
   blogPageData,