@binarynoir/vitepress-blog 0.3.0 → 0.5.0

package/dist/vitepress.cjs

@@ -64,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;
@@ -77,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;
@@ -111,7 +116,7 @@ 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) {
@@ -120,7 +125,7 @@ function listAnnouncements(pages, drafts) {
 function findAnnouncementBlog(pages, announcements, drafts) {
   if (announcements.length === 0) return null;
   const listingAll = pages.filter(isIndex).filter((index) => {
-    const listed = listBlogPosts(pages, index, { drafts, stickyFirst: false, applyLimit: false });
+    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);
@@ -137,18 +142,28 @@ var DEFAULT_LABELS = {
   older: "Older post",
   allPosts: "All posts in {blog}",
   draft: "Draft",
-  sticky: "Pinned",
+  pinned: "Pinned",
   announcement: "Announcement",
   announcements: "Announcements",
-  noAnnouncements: "No 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}.",
+  more: "+{n} more",
+  less: "Show fewer",
+  filter: "Filter {row}",
+  noFilterMatches: "Nothing matches.",
   previous: "Previous",
   next: "Next",
   pages: "Pages",
@@ -319,6 +334,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";
@@ -329,6 +351,8 @@ var FENCED_CODE = /^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^[ \t]*\1[`~]*[ \t]*$|
 var HEADING_1 = /^ {0,3}#[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/m;
 var TAG_SYNTAX = /\(\(<?tag([|/])[^|/)\r\n]*(?:\1[^|/)\r\n]*){0,2}\)\)/g;
 var MAX_SUMMARY_LENGTH = 200;
+var DEFAULT_CATEGORY_LIMIT = 8;
+var DEFAULT_TAG_LIMIT = 12;
 function readFrontmatter(raw) {
   const source = raw.replace(/^/, "");
   const match = FRONTMATTER.exec(source);
@@ -442,7 +466,8 @@ 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,
@@ -455,6 +480,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`;
@@ -488,13 +516,20 @@ 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,
+    categoryLimit: toCount(options.categoryLimit, DEFAULT_CATEGORY_LIMIT),
     tagList: options.tagList !== false,
+    tagLimit: toCount(options.tagLimit, DEFAULT_TAG_LIMIT),
+    tagMinCount: toCount(options.tagMinCount, 1),
+    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)
   };
@@ -622,7 +657,8 @@ function renderRssLink(index, context, show = index.index.rssLink) {
   if (!show || !context.feeds || !index.index.feed) return "";
   const title = fill(context.labels.rssFeed, { blog: index.title }).replace(/"/g, "&quot;");
   const url = toMarkdownUrl(`/${toFeedPath(index)}`);
-  return `<span class="vp-blog-rss">[${RSS_ICON} ${escapeMarkdown(context.labels.subscribe)}](${url} "${title}")</span>`;
+  const text = `<span class="vp-blog-rss__text">${escapeMarkdown(context.labels.subscribe)}</span>`;
+  return `<span class="vp-blog-rss">[${RSS_ICON} ${text}](${url} "${title}")</span>`;
 }
 function fill(template, values) {
   return template.replace(/\{(\w+)\}/g, (match, key) => values[key] ?? match);
@@ -652,27 +688,33 @@ 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) {
-  return `data-vp-blog-item data-tags="${toTagsAttribute(post)}"${post.post.announcement ? " data-announcement" : ""}`;
+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, sticky, announcement } = post.post;
+  const { draft, pinned, announcement } = post.post;
   return [
     draft && renderBadge("draft", context),
-    sticky && renderBadge("sticky", context),
+    pinned && renderBadge("pinned", context),
     announcement && renderBadge("announcement", context)
   ].filter(Boolean).join(" ");
 }
@@ -707,7 +749,7 @@ 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",
@@ -715,9 +757,10 @@ function renderCard(post, context, index) {
   ].filter(Boolean).map((modifier) => ` vp-blog-card--${modifier}`).join("");
   const alt = escapeMarkdown(post.post.imageAlt);
   return [
-    `<article class="vp-blog-card${modifiers}"${imageStyle(post)} ${toItemAttributes(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)),
@@ -729,7 +772,7 @@ function renderCard(post, context, index) {
 function renderCompactItem(post, context) {
   const date = post.post.date ? `${renderTime(post.post.date, post.post.dateHasTime, context)} ` : "";
   const badges = renderBadges(post, context);
-  const marker = `<span hidden ${toItemAttributes(post)}></span>`;
+  const marker = `<span hidden ${toItemAttributes(post, context)}></span>`;
   return `- ${marker}${date}${toPageLink(post.post.title, post.routePath)}${badges ? ` ${badges}` : ""}`;
 }
 function renderGroup(posts, index, context) {
@@ -749,18 +792,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),
       "",
@@ -769,29 +817,107 @@ 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(row) {
+  const { facet, label, chips, ariaLabel = label, limit = 0, attributes = "", aside = "" } = row;
+  const limited = limit && chips.length > limit ? ` data-limit="${limit}"` : "";
   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}"${limited}${attributes}>`,
+    `<span class="vp-blog-facet__label" aria-hidden="true">${escapeTemplateText(label)}</span>`,
+    '<div class="vp-blog-facet__chips">',
     "",
-    `${label} ${links.join(" ")}`,
+    chips.join(" "),
     "",
+    "</div>",
+    ...block("vp-blog-facet__aside", aside),
+    "</div>"
+  ];
+}
+function canNarrow(values, total) {
+  return values.length > 1 || values.length === 1 && values[0].count < total;
+}
+function byUse(a, b) {
+  return b.count - a.count || a.value.localeCompare(b.value, void 0, { sensitivity: "base" });
+}
+function renderBrowse(posts, index, context) {
+  const { labels } = context;
+  const { locale, timeZone } = context.dates;
+  const { categoryList, categoryLimit, tagList, tagLimit, tagMinCount, archive: showArchive } = index.index;
+  const blog = index.routePath;
+  const rows = [];
+  const categories = categoryList ? collectCategories(posts).sort(byUse) : [];
+  if (canNarrow(categories, posts.length)) {
+    const chips = categories.map(({ value, count }) => renderChip(value, count, toFilterUrl(blog, "category", value)));
+    rows.push({ facet: "category", label: labels.categories, chips, limit: categoryLimit });
+  }
+  const tags = tagList ? collectTags(posts).map(({ tag, count }) => ({ value: tag, count })).filter(({ count }) => count >= tagMinCount).sort(byUse) : [];
+  if (canNarrow(tags, posts.length)) {
+    const chips = tags.map(({ value, count }) => renderChip(value, count, toFilterUrl(blog, "tag", value)));
+    rows.push({ facet: "tag", label: labels.tags, chips, limit: tagLimit });
+  }
+  const archive = showArchive ? collectArchive(posts, timeZone) : [];
+  const monthChips = (months) => months.map(
+    ({ value, count }) => renderChip(
+      formatMonth(value, locale, { month: "short" }),
+      count,
+      toFilterUrl(blog, "month", value),
+      formatMonth(value, locale, { month: "long", year: "numeric" })
+    )
+  );
+  if (archive.length === 1 && canNarrow(archive[0].months, posts.length)) {
+    const [year] = archive;
+    const ariaLabel = `${labels.archive} ${year.value}`;
+    const attributes = ` data-year="${year.value}"`;
+    rows.push({ facet: "month", label: labels.archive, chips: monthChips(year.months), ariaLabel, attributes });
+  } else if (archive.length > 1) {
+    const years = archive.map(({ value, count }) => renderChip(value, count, toFilterUrl(blog, "year", value)));
+    rows.push({ facet: "year", label: labels.archive, chips: years });
+    for (const year of archive) {
+      const ariaLabel = `${labels.archive} ${year.value}`;
+      const attributes = ` data-year="${year.value}" hidden`;
+      rows.push({ facet: "month", label: year.value, chips: monthChips(year.months), ariaLabel, attributes });
+    }
+  }
+  if (rows.length === 0) return [];
+  rows[0].aside = renderRssLink(index, context);
+  return [
+    `<nav class="vp-blog-browse" aria-label="${escapeHtml(labels.browse)}">`,
+    ...rows.flatMap(renderFacet),
     "</nav>"
   ];
 }
@@ -799,14 +925,23 @@ 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-announcements": labels.announcements,
-    "data-label-no-announcements": labels.noAnnouncements
+    "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,
+    "data-label-more": labels.more,
+    "data-label-less": labels.less,
+    "data-label-filter": labels.filter,
+    "data-label-no-filter-matches": labels.noFilterMatches
   };
   return Object.entries(attributes).map(([name, value]) => `${name}="${escapeHtml(value)}"`).join(" ");
 }
@@ -814,20 +949,19 @@ function renderPostList(pinned, rest, index, context) {
   const all = [...pinned, ...rest];
   if (all.length === 0) return `<p class="vp-blog-empty">${escapeTemplateText(context.labels.noPosts)}</p>
 `;
+  const browse = renderBrowse(all, 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>'
+    ...browse.length ? browse : block("vp-blog-subscribe", renderRssLink(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")}
 `;
@@ -836,8 +970,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}`;
@@ -928,7 +1066,7 @@ function toOptionsKey(options) {
     options.wordsPerMinute,
     options.stripTags,
     options.pageSize,
-    options.stickyLimit,
+    options.pinLimit ?? options.stickyLimit,
     options.rssLink,
     options.timeZone
   ]);
@@ -1017,10 +1155,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
     },
@@ -1036,19 +1177,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">`];
@@ -1121,8 +1262,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, () => `
@@ -1145,7 +1286,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)}
@@ -1222,7 +1363,7 @@ function attachAnnouncements(siteConfig, options = {}) {
 }
 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({