@binarynoir/vitepress-blog 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { B as BlogAnnouncementData, a as BlogAnnouncementItem, b as BlogAuthor, c as BlogFeedConfig, d as BlogIndexConfig, e as BlogLabels, f as BlogLayout, g as BlogOptions, h as BlogPostData, i as BlogScope, D as DEFAULT_LABELS, j as blogMarkdown } from './plugin-Bb4rRwO8.cjs';
+export { B as BlogAnnouncementData, a as BlogAnnouncementItem, b as BlogAuthor, c as BlogFeedConfig, d as BlogGroupBy, e as BlogIndexConfig, f as BlogLabels, g as BlogLayout, h as BlogOptions, i as BlogPostData, j as BlogScope, D as DEFAULT_LABELS, k as blogMarkdown } from './plugin-DUTUA_t4.cjs';
 import 'markdown-it';
 
 /** Marker a blog page can use to say where its list of posts goes. Without it the list is appended. */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { B as BlogAnnouncementData, a as BlogAnnouncementItem, b as BlogAuthor, c as BlogFeedConfig, d as BlogIndexConfig, e as BlogLabels, f as BlogLayout, g as BlogOptions, h as BlogPostData, i as BlogScope, D as DEFAULT_LABELS, j as blogMarkdown } from './plugin-Bb4rRwO8.js';
+export { B as BlogAnnouncementData, a as BlogAnnouncementItem, b as BlogAuthor, c as BlogFeedConfig, d as BlogGroupBy, e as BlogIndexConfig, f as BlogLabels, g as BlogLayout, h as BlogOptions, i as BlogPostData, j as BlogScope, D as DEFAULT_LABELS, k as blogMarkdown } from './plugin-DUTUA_t4.js';
 import 'markdown-it';
 
 /** Marker a blog page can use to say where its list of posts goes. Without it the list is appended. */

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   POST_FRONTMATTER_KEY,
   WIDGET_NAME,
   blogMarkdown
-} from "./chunk-LYTJBMVK.js";
+} from "./chunk-ZM5FOUT4.js";
 import "./chunk-42Z6H7IN.js";
 export {
   BLOG_POSTS_PLACEHOLDER,

package/dist/{plugin-Bb4rRwO8.d.cts → plugin-DUTUA_t4.d.cts}

@@ -64,10 +64,12 @@ interface BlogOptions {
      */
     pageSize?: number;
     /**
-     * Most sticky posts pinned to the top of a blog page, for those that don't
-     * set `stickyLimit`. Extra sticky posts take their place by date. `0` pins
-     * them all. Default: `0`.
+     * Most `pinned: true` posts kept at the top of a blog page, for those that
+     * don't set `pinLimit`. Extra pinned posts take their place by date. `0`
+     * pins them all. Default: `0`.
      */
+    pinLimit?: number;
+    /** @deprecated Renamed `pinLimit`; still read when `pinLimit` isn't set. */
     stickyLimit?: number;
     /**
      * Show a "Subscribe" RSS link on blog pages and `::: blog-posts` blocks,
@@ -75,7 +77,7 @@ interface BlogOptions {
      * on a site with a site URL (without one, no feeds are written). Default: `true`.
      */
     rssLink?: boolean;
-    /** Words the plugin writes on pages, for translating. `{n}`, `{blog}` and `{tag}` are filled in. */
+    /** Words the plugin writes on pages, for translating. `{n}`, `{blog}` and `{filter}` are filled in. */
     labels?: Partial<BlogLabels>;
 }
 interface BlogLabels {
@@ -94,29 +96,41 @@ interface BlogLabels {
     /** The link back to a post's blog: "All posts in {blog}". */
     allPosts: string;
     draft: string;
-    /** Badge on a sticky post. */
-    sticky: string;
+    /** Badge on a pinned post. */
+    pinned: string;
     /** Badge on an announcement, and the accessible name of the announcement banner. */
     announcement: string;
-    /** Above a blog page filtered to announcements (`?announcements`). */
+    /** A blog page's announcements filter (`?announcements`), in the active filters. */
     announcements: string;
-    /** When the blog page has no announcements to show. */
-    noAnnouncements: string;
     /** Tooltip of the banner's count badge: "{n} announcements". */
     announcementCount: string;
     /** Accessible name of the banner's close button. */
     dismiss: string;
     noPosts: string;
-    /** Year heading for posts without a date, when a blog groups by year. */
+    /** Group heading for posts without a date, when a blog groups by year or month. */
     undated: string;
-    /** Label of a blog page's keyword list. */
+    /** Accessible name of the browse panel above a blog page's posts. */
+    browse: string;
+    /** Label of the browse panel's category row. */
+    categories: string;
+    /** Label of the browse panel's keyword row. */
     tags: string;
-    /** Above a list filtered by keyword: "Posts tagged {tag}". */
-    tagged: string;
-    /** Link that clears the keyword filter. */
+    /** Label of the browse panel's year row. */
+    archive: string;
+    /** Names a category filter among the active filters: "Category". */
+    category: string;
+    /** Names a keyword filter among the active filters: "Keyword". */
+    tag: string;
+    /** How many posts the active filters match: "{n} posts". */
+    postCount: string;
+    /** The same, for one post: "{n} post". */
+    postCountOne: string;
+    /** When no post matches the active filters. */
+    noMatches: string;
+    /** Accessible name of an active filter's remove link: "Remove filter: {filter}". */
+    removeFilter: string;
+    /** Link that clears every filter. */
     showAll: string;
-    /** When no post has the keyword: "No posts tagged {tag}." */
-    noTagged: string;
     previous: string;
     next: string;
     /** Accessible name of the page links. */
@@ -129,6 +143,8 @@ interface BlogLabels {
 declare const DEFAULT_LABELS: BlogLabels;
 type BlogScope = 'site' | 'section';
 type BlogLayout = 'list' | 'grid' | 'compact';
+/** How a blog page groups its posts under headings: by year, by month, or not at all (`''`). */
+type BlogGroupBy = 'year' | 'month' | '';
 interface BlogFeedConfig {
     title?: string;
     description?: string;
@@ -144,19 +160,27 @@ interface BlogIndexConfig {
     folders: string[];
     /** Only list posts with at least one of these tags. */
     tags: string[];
+    /** Only list posts in one of these categories. */
+    categories: string[];
     /** Most posts to list. `0` lists them all. */
     limit: number;
     layout: BlogLayout;
-    /** Put a year heading above each year's posts. */
-    groupByYear: boolean;
+    /** Put a heading above each year's or month's posts. */
+    groupBy: BlogGroupBy;
     /** Show the post's tags on each card. */
     showTags: boolean;
+    /** Show the post's category above its title on each card. */
+    showCategory: boolean;
+    /** List every category above the posts, each one a filter. */
+    categoryList: boolean;
     /** List every keyword above the posts, each one a filter. */
     tagList: boolean;
+    /** List the years and months that have posts above the posts, each one a filter. */
+    archive: boolean;
     /** Posts per page. `0` shows them all on one page. */
     pageSize: number;
-    /** Most sticky posts pinned to the top. `0` pins them all. */
-    stickyLimit: number;
+    /** Most pinned posts kept at the top. `0` pins them all. */
+    pinLimit: number;
     /** Show a "Subscribe" link to the blog's feed. */
     rssLink: boolean;
     feed: BlogFeedConfig | null;
@@ -184,7 +208,7 @@ interface BlogPostData {
     tags: string[];
     category: string;
     scope: BlogScope;
-    sticky: boolean;
+    pinned: boolean;
     draft: boolean;
     /** Shown in the announcement banner above the nav bar. */
     announcement: boolean;
@@ -240,4 +264,4 @@ interface BlogAnnouncementData {
  */
 declare function blogMarkdown(md: MarkdownIt, options?: BlogOptions): void;
 
-export { type BlogAnnouncementData as B, DEFAULT_LABELS as D, type BlogAnnouncementItem as a, type BlogAuthor as b, type BlogFeedConfig as c, type BlogIndexConfig as d, type BlogLabels as e, type BlogLayout as f, type BlogOptions as g, type BlogPostData as h, type BlogScope as i, blogMarkdown as j };
+export { type BlogAnnouncementData as B, DEFAULT_LABELS as D, type BlogAnnouncementItem as a, type BlogAuthor as b, type BlogFeedConfig as c, type BlogGroupBy as d, type BlogIndexConfig as e, type BlogLabels as f, type BlogLayout as g, type BlogOptions as h, type BlogPostData as i, type BlogScope as j, blogMarkdown as k };

package/dist/{plugin-Bb4rRwO8.d.ts → plugin-DUTUA_t4.d.ts}

@@ -64,10 +64,12 @@ interface BlogOptions {
      */
     pageSize?: number;
     /**
-     * Most sticky posts pinned to the top of a blog page, for those that don't
-     * set `stickyLimit`. Extra sticky posts take their place by date. `0` pins
-     * them all. Default: `0`.
+     * Most `pinned: true` posts kept at the top of a blog page, for those that
+     * don't set `pinLimit`. Extra pinned posts take their place by date. `0`
+     * pins them all. Default: `0`.
      */
+    pinLimit?: number;
+    /** @deprecated Renamed `pinLimit`; still read when `pinLimit` isn't set. */
     stickyLimit?: number;
     /**
      * Show a "Subscribe" RSS link on blog pages and `::: blog-posts` blocks,
@@ -75,7 +77,7 @@ interface BlogOptions {
      * on a site with a site URL (without one, no feeds are written). Default: `true`.
      */
     rssLink?: boolean;
-    /** Words the plugin writes on pages, for translating. `{n}`, `{blog}` and `{tag}` are filled in. */
+    /** Words the plugin writes on pages, for translating. `{n}`, `{blog}` and `{filter}` are filled in. */
     labels?: Partial<BlogLabels>;
 }
 interface BlogLabels {
@@ -94,29 +96,41 @@ interface BlogLabels {
     /** The link back to a post's blog: "All posts in {blog}". */
     allPosts: string;
     draft: string;
-    /** Badge on a sticky post. */
-    sticky: string;
+    /** Badge on a pinned post. */
+    pinned: string;
     /** Badge on an announcement, and the accessible name of the announcement banner. */
     announcement: string;
-    /** Above a blog page filtered to announcements (`?announcements`). */
+    /** A blog page's announcements filter (`?announcements`), in the active filters. */
     announcements: string;
-    /** When the blog page has no announcements to show. */
-    noAnnouncements: string;
     /** Tooltip of the banner's count badge: "{n} announcements". */
     announcementCount: string;
     /** Accessible name of the banner's close button. */
     dismiss: string;
     noPosts: string;
-    /** Year heading for posts without a date, when a blog groups by year. */
+    /** Group heading for posts without a date, when a blog groups by year or month. */
     undated: string;
-    /** Label of a blog page's keyword list. */
+    /** Accessible name of the browse panel above a blog page's posts. */
+    browse: string;
+    /** Label of the browse panel's category row. */
+    categories: string;
+    /** Label of the browse panel's keyword row. */
     tags: string;
-    /** Above a list filtered by keyword: "Posts tagged {tag}". */
-    tagged: string;
-    /** Link that clears the keyword filter. */
+    /** Label of the browse panel's year row. */
+    archive: string;
+    /** Names a category filter among the active filters: "Category". */
+    category: string;
+    /** Names a keyword filter among the active filters: "Keyword". */
+    tag: string;
+    /** How many posts the active filters match: "{n} posts". */
+    postCount: string;
+    /** The same, for one post: "{n} post". */
+    postCountOne: string;
+    /** When no post matches the active filters. */
+    noMatches: string;
+    /** Accessible name of an active filter's remove link: "Remove filter: {filter}". */
+    removeFilter: string;
+    /** Link that clears every filter. */
     showAll: string;
-    /** When no post has the keyword: "No posts tagged {tag}." */
-    noTagged: string;
     previous: string;
     next: string;
     /** Accessible name of the page links. */
@@ -129,6 +143,8 @@ interface BlogLabels {
 declare const DEFAULT_LABELS: BlogLabels;
 type BlogScope = 'site' | 'section';
 type BlogLayout = 'list' | 'grid' | 'compact';
+/** How a blog page groups its posts under headings: by year, by month, or not at all (`''`). */
+type BlogGroupBy = 'year' | 'month' | '';
 interface BlogFeedConfig {
     title?: string;
     description?: string;
@@ -144,19 +160,27 @@ interface BlogIndexConfig {
     folders: string[];
     /** Only list posts with at least one of these tags. */
     tags: string[];
+    /** Only list posts in one of these categories. */
+    categories: string[];
     /** Most posts to list. `0` lists them all. */
     limit: number;
     layout: BlogLayout;
-    /** Put a year heading above each year's posts. */
-    groupByYear: boolean;
+    /** Put a heading above each year's or month's posts. */
+    groupBy: BlogGroupBy;
     /** Show the post's tags on each card. */
     showTags: boolean;
+    /** Show the post's category above its title on each card. */
+    showCategory: boolean;
+    /** List every category above the posts, each one a filter. */
+    categoryList: boolean;
     /** List every keyword above the posts, each one a filter. */
     tagList: boolean;
+    /** List the years and months that have posts above the posts, each one a filter. */
+    archive: boolean;
     /** Posts per page. `0` shows them all on one page. */
     pageSize: number;
-    /** Most sticky posts pinned to the top. `0` pins them all. */
-    stickyLimit: number;
+    /** Most pinned posts kept at the top. `0` pins them all. */
+    pinLimit: number;
     /** Show a "Subscribe" link to the blog's feed. */
     rssLink: boolean;
     feed: BlogFeedConfig | null;
@@ -184,7 +208,7 @@ interface BlogPostData {
     tags: string[];
     category: string;
     scope: BlogScope;
-    sticky: boolean;
+    pinned: boolean;
     draft: boolean;
     /** Shown in the announcement banner above the nav bar. */
     announcement: boolean;
@@ -240,4 +264,4 @@ interface BlogAnnouncementData {
  */
 declare function blogMarkdown(md: MarkdownIt, options?: BlogOptions): void;
 
-export { type BlogAnnouncementData as B, DEFAULT_LABELS as D, type BlogAnnouncementItem as a, type BlogAuthor as b, type BlogFeedConfig as c, type BlogIndexConfig as d, type BlogLabels as e, type BlogLayout as f, type BlogOptions as g, type BlogPostData as h, type BlogScope as i, blogMarkdown as j };
+export { type BlogAnnouncementData as B, DEFAULT_LABELS as D, type BlogAnnouncementItem as a, type BlogAuthor as b, type BlogFeedConfig as c, type BlogGroupBy as d, type BlogIndexConfig as e, type BlogLabels as f, type BlogLayout as g, type BlogOptions as h, type BlogPostData as i, type BlogScope as j, blogMarkdown as k };

package/dist/style.css

@@ -10,6 +10,9 @@
   --vp-blog-tag-bg: var(--vp-c-default-soft);
   --vp-blog-tag-color: var(--vp-c-text-2);
   --vp-blog-accent: var(--vp-c-brand-1);
+  --vp-blog-browse-bg: var(--vp-c-bg-soft);
+  /* Width of the label column in the browse panel, so every row's chips line up. */
+  --vp-blog-facet-label-width: 6.5rem;
   --vp-blog-announcement-height: 40px;
   --vp-blog-announcement-bg: var(--vp-button-brand-bg);
   --vp-blog-announcement-color: var(--vp-button-brand-text);
@@ -46,7 +49,7 @@
   border-color: var(--vp-blog-accent);
 }
 
-.vp-blog-card--sticky {
+.vp-blog-card--pinned {
   border-color: var(--vp-blog-accent);
 }
 
@@ -86,6 +89,28 @@
   padding: 16px 20px 20px;
 }
 
+/* The category, above the title: a small linked eyebrow. */
+.vp-blog-card__category {
+  margin-bottom: -4px;
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  line-height: 1.4;
+  text-transform: uppercase;
+}
+
+.vp-blog-card .vp-blog-card__category a {
+  color: var(--vp-blog-accent);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.vp-blog-card .vp-blog-card__category a:hover,
+.vp-blog-card .vp-blog-card__category a.is-active {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
 .vp-blog-card__title {
   font-size: 18px;
   font-weight: 600;
@@ -165,9 +190,11 @@
 }
 
 .vp-blog-tag,
+.vp-blog-category,
 .vp-blog-badge,
-.vp-blog-tags a,
+.vp-blog-facet a,
 .vp-blog-card__tags a,
+.vp-blog-byline__category a,
 .vp-blog-byline__tags a {
   display: inline-block;
   margin: 2px 4px 2px 0;
@@ -180,26 +207,37 @@
   line-height: 22px;
 }
 
-/* Keyword chips are links that filter their blog. */
-.vp-blog .vp-blog-tags a,
+/* Chips are links that filter their blog. */
+.vp-blog .vp-blog-facet a,
 .vp-blog .vp-blog-card__tags a,
+.vp-blog-byline__category a,
 .vp-blog-byline__tags a {
   text-decoration: none;
   transition:
     background-color 0.25s,
-    color 0.25s;
+    color 0.25s,
+    opacity 0.25s;
 }
 
-.vp-blog .vp-blog-tags a:hover,
+.vp-blog .vp-blog-facet a:hover,
 .vp-blog .vp-blog-card__tags a:hover,
+.vp-blog-byline__category a:hover,
 .vp-blog-byline__tags a:hover,
-.vp-blog-tags a.is-active,
-.vp-blog-card__tags a.is-active {
+.vp-blog .vp-blog-facet a.is-active,
+.vp-blog .vp-blog-card__tags a.is-active {
   background: var(--vp-c-brand-soft);
   color: var(--vp-blog-accent);
 }
 
-.vp-blog-badge--sticky {
+/* A post's category in its byline: a chip in the accent, ahead of its keywords. */
+.vp-blog-category,
+.vp-blog-byline__category a {
+  background: var(--vp-c-brand-soft);
+  color: var(--vp-blog-accent);
+  font-weight: 600;
+}
+
+.vp-blog-badge--pinned {
   background: var(--vp-c-brand-soft);
   color: var(--vp-c-brand-1);
 }
@@ -266,29 +304,53 @@
   }
 }
 
-/* The blog: keyword list, filter banner, pinned posts and page links. */
+/* The blog: browse panel, active filters, pinned posts and page links. */
 .vp-blog {
   scroll-margin-top: calc(var(--vp-nav-height, 64px) + 24px);
 }
 
-.vp-blog-tags {
-  margin: 16px 0 8px;
-  line-height: 2;
+/*
+ * The browse panel: one row each for categories, keywords and years, and the
+ * months of the year in view below the years. Labels sit in a column of their
+ * own on wide screens, above their chips on narrow ones.
+ */
+.vp-blog-browse {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  margin: 16px 0;
+  padding: 14px 16px;
+  border: 1px solid var(--vp-blog-card-border);
+  border-radius: var(--vp-blog-card-radius);
+  background: var(--vp-blog-browse-bg);
 }
 
-.vp-blog-tags p {
-  margin: 0;
+.vp-blog-facet {
+  display: grid;
+  grid-template-columns: var(--vp-blog-facet-label-width) minmax(0, 1fr);
+  gap: 2px 12px;
+  align-items: baseline;
 }
 
-.vp-blog-tags__label {
-  margin-right: 8px;
+.vp-blog-facet__label {
   color: var(--vp-blog-meta-color);
-  font-size: 14px;
+  font-size: 13px;
   font-weight: 600;
+  line-height: 26px;
+}
+
+/* A year's months: tucked under the years, their label the year. */
+.vp-blog-facet--month .vp-blog-facet__label {
+  font-variant-numeric: tabular-nums;
+  font-weight: 500;
 }
 
-/* The post count in a keyword pill: a small counter badge inside it. */
-.vp-blog-tags__count {
+.vp-blog-facet__chips p {
+  margin: 0;
+}
+
+/* The post count in a chip: a small counter badge inside it. */
+.vp-blog-facet__count {
   display: inline-block;
   min-width: 18px;
   margin-left: 6px;
@@ -307,14 +369,38 @@
     color 0.25s;
 }
 
-.vp-blog-tags a:hover .vp-blog-tags__count,
-.vp-blog-tags a.is-active .vp-blog-tags__count {
+.vp-blog-facet a:hover .vp-blog-facet__count,
+.vp-blog-facet a.is-active .vp-blog-facet__count {
   background: var(--vp-blog-accent);
   /* The page background, so the number stays readable on the accent in light and dark mode. */
   color: var(--vp-c-bg);
 }
 
+/* A chip that would show no posts with the other filters kept. */
+.vp-blog .vp-blog-facet a.is-empty {
+  opacity: 0.45;
+}
+
+.vp-blog .vp-blog-facet a.is-empty:hover {
+  opacity: 0.8;
+}
+
+@media (max-width: 639px) {
+  .vp-blog-facet {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .vp-blog-facet__label {
+    line-height: 20px;
+  }
+}
+
+/* The active filters: how many posts match, a removable chip for each filter, and a link to clear them all. */
 .vp-blog-filter {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: center;
   margin: 16px 0;
   padding: 10px 16px;
   border-radius: 8px;
@@ -322,15 +408,61 @@
   font-size: 14px;
 }
 
+.vp-blog-filter__count {
+  margin-right: 4px;
+  color: var(--vp-c-text-1);
+  font-weight: 600;
+}
+
+.vp-blog .vp-blog-filter__chip {
+  display: inline-flex;
+  gap: 4px;
+  align-items: center;
+  padding: 0 4px 0 10px;
+  border: 1px solid var(--vp-blog-accent);
+  border-radius: 999px;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  font-size: 13px;
+  font-weight: 500;
+  line-height: 24px;
+  text-decoration: none;
+}
+
+.vp-blog-filter__kind {
+  color: var(--vp-blog-meta-color);
+  font-weight: 400;
+}
+
+.vp-blog-filter__remove {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  color: var(--vp-blog-meta-color);
+  font-size: 14px;
+  line-height: 1;
+  transition:
+    background-color 0.25s,
+    color 0.25s;
+}
+
+.vp-blog .vp-blog-filter__chip:hover .vp-blog-filter__remove {
+  background: var(--vp-c-brand-soft);
+  color: var(--vp-blog-accent);
+}
+
 .vp-blog-filter__clear {
-  margin-left: 8px;
+  margin-left: auto;
 }
 
-.vp-blog-sticky {
+.vp-blog-pinned {
   margin: 24px 0;
 }
 
-.vp-blog-sticky .vp-blog-list {
+.vp-blog-pinned .vp-blog-list {
   margin: 0;
 }