@binarynoir/vitepress-blog 0.2.0 → 0.4.0

package/dist/{chunk-PWNWSYI4.js → chunk-ZM5FOUT4.js}

@@ -1,3 +1,14 @@
+import {
+  escapeHtml,
+  escapeMarkdown,
+  escapeTemplateText,
+  isExternalUrl,
+  joinUrl,
+  toMarkdownUrl,
+  toPageLink,
+  toUrlPath
+} from "./chunk-42Z6H7IN.js";
+
 // src/collect.ts
 function isPost(page) {
   return page.post !== null;
@@ -19,6 +30,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;
@@ -32,22 +48,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;
@@ -66,43 +82,19 @@ 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)
   );
 }
-
-// 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 listAnnouncements(pages, drafts) {
+  return pages.filter(isPost).filter((post) => post.post.announcement && (drafts || !post.post.draft)).sort(compareByDate);
 }
-function toUrlPath(routePath, cleanUrls) {
-  return `/${routePath.replace(/(^|\/)index\.md$/, "$1").replace(/\.md$/, cleanUrls ? "" : ".html")}`;
-}
-function joinUrl(base, urlPath) {
-  return `${base.replace(/\/+$/, "")}/${urlPath.replace(/^\/+/, "")}`;
+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/feed.ts
@@ -210,13 +202,24 @@ var DEFAULT_LABELS = {
   older: "Older post",
   allPosts: "All posts in {blog}",
   draft: "Draft",
-  sticky: "Pinned",
+  pinned: "Pinned",
+  announcement: "Announcement",
+  announcements: "Announcements",
+  announcementCount: "{n} announcements",
+  dismiss: "Dismiss",
   noPosts: "No posts yet.",
   undated: "Undated",
+  browse: "Browse posts",
+  categories: "Categories",
   tags: "Keywords",
-  tagged: "Posts tagged {tag}",
+  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",
-  noTagged: "No posts tagged {tag}.",
   previous: "Previous",
   next: "Next",
   pages: "Pages",
@@ -322,6 +325,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/render.ts
 var BLOG_POSTS_PLACEHOLDER = "<!-- blog-posts -->";
@@ -377,25 +387,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) {
@@ -422,16 +448,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)),
@@ -442,8 +470,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) {
@@ -463,18 +491,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),
       "",
@@ -483,42 +516,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(" ");
 }
@@ -529,17 +634,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")}
 `;
@@ -548,8 +652,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}`;
@@ -684,6 +792,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)),
@@ -699,8 +808,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),
@@ -710,6 +822,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 = path3.posix.basename(relativePath, ".md");
   return name === "index" ? "feed.xml" : `${name}-feed.xml`;
@@ -743,13 +858,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)
   };
@@ -819,7 +938,7 @@ function toOptionsKey(options) {
     options.wordsPerMinute,
     options.stripTags,
     options.pageSize,
-    options.stickyLimit,
+    options.pinLimit ?? options.stickyLimit,
     options.rssLink,
     options.timeZone
   ]);
@@ -908,10 +1027,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
     },
@@ -927,19 +1049,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">`];
@@ -1013,8 +1135,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, path6.dirname(page.absolutePath), hasFeeds(options));
   const generated = renderPostList(pinned, rest, page, context);
   return source.includes(BLOG_POSTS_PLACEHOLDER) ? source.replace(BLOG_POSTS_PLACEHOLDER, () => `
@@ -1037,7 +1159,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)}
@@ -1088,7 +1210,8 @@ export {
   isIndex,
   listBlogPosts,
   findBlogsListing,
-  joinUrl,
+  listAnnouncements,
+  findAnnouncementBlog,
   toPageUrl,
   toFeedPath,
   resolvePostImage,
@@ -1105,4 +1228,4 @@ export {
   hasWidget,
   blogMarkdown
 };
-//# sourceMappingURL=chunk-PWNWSYI4.js.map
+//# sourceMappingURL=chunk-ZM5FOUT4.js.map