@binarynoir/vitepress-blog 0.2.0 → 0.3.0

package/README.md

@@ -155,7 +155,8 @@ blog:
 | `category`      | none                                       | Written to the feed and `article:section`.                                                                                                                |
 | `scope`         | `section`                                  | `site` (or `global`) also lists the post on the main blog. See [Scopes](#scopes).                                                                         |
 | `sticky`        | `false`                                    | Pinned to the top of its blog pages, above the paginated posts, with a Pinned badge. See [Sticky posts](#sticky-posts).                                   |
-| `draft`         | `false`                                    | Left out of lists and feeds. The page itself is still built: use `srcExclude` to hide it.                                                                 |
+| `announcement`  | `false`                                    | `true`, or the banner's text, shows the post in the announcement banner above the nav bar. See [Announcements](#announcements).                           |
+| `draft`         | `false`                                    | Left out of lists and feeds. The page itself is still built: to leave drafts out of the build, the sidebar and the navbar too, see [Drafts](#drafts).     |
 | `byline`        | the `byline` option                        | `false` hides this post's byline.                                                                                                                         |
 | `cover`         | the `cover` option                         | `true` shows this post's image under its byline.                                                                                                          |
 | `postNav`       | the `postNav` option                       | `false` hides this post's newer / older links.                                                                                                            |
@@ -196,6 +197,35 @@ blog:
 - Feeds and social tags use the exact moment: `pubDate`, `lastBuildDate`,
   `article:published_time` and `article:modified_time`.
 
+### Drafts
+
+`draft: true` keeps a post out of blog lists, `::: blog-posts` blocks and
+feeds, but the page is still built and can be opened by its URL. With the
+`drafts` option on, drafts are listed too, with a Draft badge, which is handy in
+`vitepress dev`.
+
+To leave drafts out of the build entirely, use
+[`@binarynoir/vitepress-exclude`](https://binarynoir.tech/plugins/exclude/)'s
+`excludeFrontmatter` option, and the same option in Auto Sidebar and Auto
+Navbar to hide them from the menus. The blog lists only what VitePress builds,
+so nothing else changes:
+
+```ts
+// Drafts stay out of the production build, and show (marked) in `vitepress dev`.
+const isBuild = process.env.NODE_ENV === 'production';
+const excludeFrontmatter = isBuild ? ['draft', 'blog.draft'] : [];
+const blogOptions = { drafts: !isBuild };
+
+export default defineConfig({
+  srcExclude: excludeSrc(docsRoot, { excludeFrontmatter }),
+  themeConfig: {
+    sidebar: generateSidebar(docsRoot, { excludeFrontmatter }),
+    nav: generateNav(docsRoot, { excludeFrontmatter }),
+  },
+  // ...the blog's pieces, with blogOptions
+});
+```
+
 ## Blog pages
 
 A page with `blog-index` in its frontmatter lists posts. `blog-index: true` is a
@@ -270,6 +300,57 @@ a blog page, on each card, and in a post's byline, where they link to the
 post's own blog, filtered. They are ordinary links, so VitePress follows them
 without reloading the page, and each filtered view has its own URL to share.
 
+## Announcements
+
+`announcement: true` puts a post in a banner across the top of every page,
+above the nav bar: one line, the full width of the window, linked to the post.
+A string sets the banner's text instead of the post's title.
+
+```md
+---
+blog:
+  date: 2026-10-20 09:00
+  announcement: Scheduled maintenance on Friday, 18:00 UTC
+---
+```
+
+Add the banner to your theme's `layout-top` slot:
+
+```ts
+// .vitepress/theme/index.ts
+import { h } from 'vue';
+import DefaultTheme from 'vitepress/theme';
+import { BlogAnnouncementBanner, useBlog } from '@binarynoir/vitepress-blog/client';
+import '@binarynoir/vitepress-blog/style.css';
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => h(DefaultTheme.Layout, null, { 'layout-top': () => h(BlogAnnouncementBanner) }),
+  setup() {
+    useBlog();
+  },
+};
+```
+
+- **The newest one wins.** With several, the banner shows the newest and a
+  badge with how many there are. The badge opens a blog page filtered to
+  announcements (`/blog/?announcements`): the main blog when it lists them all,
+  else another blog page that does, else the newest one's own blog.
+- **Visitors can clear it.** The close button dismisses every current
+  announcement, remembered in the browser. A newer one brings the banner back,
+  and its badge counts only the ones not yet dismissed. Changing a post's
+  `date` announces it again.
+- **No jump on load.** The banner is rendered on the server, and a small
+  `<head>` script hides it before the page shows if the visitor dismissed it.
+  While it shows, it sets VitePress's `--vp-layout-top-height`, so the nav bar,
+  sidebar and content move down to make room.
+- Announcements are marked on blog pages with an Announcement badge. Drafts
+  are only announced with the `drafts` option.
+
+The banner reads its posts from VitePress's site data, which `withBlog` (or
+`blogVitePlugin`) fills in; `blogVitePlugin` also has Vite bundle this package
+for the server-side build, so the banner renders there.
+
 ## Latest posts on any page
 
 A `::: blog-posts` block shows a blog's latest posts anywhere: on the home
@@ -401,6 +482,11 @@ withBlog(config, {
     allPosts: 'Alle Beiträge in {blog}',
     draft: 'Entwurf',
     sticky: 'Angeheftet',
+    announcement: 'Ankündigung',
+    announcements: 'Ankündigungen',
+    noAnnouncements: 'Keine Ankündigungen.',
+    announcementCount: '{n} Ankündigungen',
+    dismiss: 'Schließen',
     noPosts: 'Noch keine Beiträge.',
     undated: 'Ohne Datum',
     tags: 'Schlagwörter',
@@ -421,15 +507,18 @@ withBlog(config, {
 `style.css` uses VitePress's theme variables, so it follows light and dark
 mode. Override these to restyle it without new rules:
 
-| Variable                | Default                    |
-| ----------------------- | -------------------------- |
-| `--vp-blog-card-bg`     | `var(--vp-c-bg-soft)`      |
-| `--vp-blog-card-border` | `var(--vp-c-divider)`      |
-| `--vp-blog-card-radius` | `12px`                     |
-| `--vp-blog-meta-color`  | `var(--vp-c-text-2)`       |
-| `--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)`      |
+| Variable                        | Default                       |
+| ------------------------------- | ----------------------------- |
+| `--vp-blog-card-bg`             | `var(--vp-c-bg-soft)`         |
+| `--vp-blog-card-border`         | `var(--vp-c-divider)`         |
+| `--vp-blog-card-radius`         | `12px`                        |
+| `--vp-blog-meta-color`          | `var(--vp-c-text-2)`          |
+| `--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-announcement-height` | `40px`                        |
+| `--vp-blog-announcement-bg`     | `var(--vp-button-brand-bg)`   |
+| `--vp-blog-announcement-color`  | `var(--vp-button-brand-text)` |
 
 Every generated element has a `vp-blog-` class (`vp-blog-card`,
 `vp-blog-byline`, `vp-blog-post-nav`, …) for anything more.

package/dist/chunk-42Z6H7IN.js

@@ -0,0 +1,52 @@
+// 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";
+
+export {
+  escapeHtml,
+  escapeMarkdown,
+  escapeTemplateText,
+  isExternalUrl,
+  toMarkdownUrl,
+  toPageLink,
+  toUrlPath,
+  joinUrl,
+  ANNOUNCEMENTS_KEY,
+  DISMISSED_STORAGE_KEY,
+  DISMISSED_CLASS
+};
+//# sourceMappingURL=chunk-42Z6H7IN.js.map

package/dist/chunk-42Z6H7IN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/util.ts"],"sourcesContent":["const HTML_ESCAPES: Record<string, string> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&#39;',\n};\n\n/** Escapes the characters that are special in HTML text and attribute values. */\nexport function escapeHtml(value: string): string {\n  return value.replace(/[&<>\"']/g, (character) => HTML_ESCAPES[character]);\n}\n\n/**\n * Escapes text so it stays literal in Markdown and in VitePress's Vue\n * templates. Text with braces goes in a `v-pre` span, since Vue would otherwise\n * evaluate `{{ }}` even when the Markdown escaped it.\n */\nexport function escapeMarkdown(text: string): string {\n  const escaped = text\n    .replace(/[\\\\`*_[\\]#|~]/g, '\\\\$&')\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;');\n  return /[{}]/.test(escaped) ? `<span v-pre>${escaped}</span>` : escaped;\n}\n\n/** HTML text that Vue leaves alone: braces go in a `v-pre` span. */\nexport function escapeTemplateText(text: string): string {\n  const escaped = escapeHtml(text);\n  return /[{}]/.test(escaped) ? `<span v-pre>${escaped}</span>` : escaped;\n}\n\n/** A URL with a scheme (`https:`, `mailto:`) or protocol-relative (`//cdn`). */\nexport function isExternalUrl(url: string): boolean {\n  return /^(?:[a-z][a-z\\d+.-]*:|\\/\\/)/i.test(url);\n}\n\n/** Encodes a URL for a Markdown link destination: spaces and parentheses would end it early. */\nexport function toMarkdownUrl(url: string): string {\n  return encodeURI(url).replace(/[()]/g, (character) => (character === '(' ? '%28' : '%29'));\n}\n\n/** A Markdown link to a page by its served path, which VitePress then checks and gives the site's base. */\nexport function toPageLink(text: string, routePath: string): string {\n  return `[${escapeMarkdown(text)}](${toMarkdownUrl(`/${routePath}`)})`;\n}\n\n/** A page's URL path, without the site's base: `news/index.md` is `/news/`, `news/launch.md` is `/news/launch`. */\nexport function toUrlPath(routePath: string, cleanUrls: boolean): string {\n  return `/${routePath.replace(/(^|\\/)index\\.md$/, '$1').replace(/\\.md$/, cleanUrls ? '' : '.html')}`;\n}\n\n/** `base` and `urlPath` joined with exactly one slash between them. */\nexport function joinUrl(base: string, urlPath: string): string {\n  return `${base.replace(/\\/+$/, '')}/${urlPath.replace(/^\\/+/, '')}`;\n}\n\n/** Where the announcement banner's data sits on VitePress's site data: `useData().site.value.blogAnnouncements`. */\nexport const ANNOUNCEMENTS_KEY = 'blogAnnouncements';\n\n/** The `localStorage` key holding the ids of the announcements a visitor dismissed, as a JSON array. */\nexport const DISMISSED_STORAGE_KEY = 'vp-blog-announcements-dismissed';\n\n/** The class on `<html>` that hides a dismissed banner before the page hydrates. */\nexport const DISMISSED_CLASS = 'vp-blog-announcement-dismissed';\n"],"mappings":";AAAA,IAAM,eAAuC;AAAA,EAC3C,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AACP;AAGO,SAAS,WAAW,OAAuB;AAChD,SAAO,MAAM,QAAQ,YAAY,CAAC,cAAc,aAAa,SAAS,CAAC;AACzE;AAOO,SAAS,eAAe,MAAsB;AACnD,QAAM,UAAU,KACb,QAAQ,kBAAkB,MAAM,EAChC,QAAQ,MAAM,OAAO,EACrB,QAAQ,MAAM,MAAM,EACpB,QAAQ,MAAM,MAAM;AACvB,SAAO,OAAO,KAAK,OAAO,IAAI,eAAe,OAAO,YAAY;AAClE;AAGO,SAAS,mBAAmB,MAAsB;AACvD,QAAM,UAAU,WAAW,IAAI;AAC/B,SAAO,OAAO,KAAK,OAAO,IAAI,eAAe,OAAO,YAAY;AAClE;AAGO,SAAS,cAAc,KAAsB;AAClD,SAAO,+BAA+B,KAAK,GAAG;AAChD;AAGO,SAAS,cAAc,KAAqB;AACjD,SAAO,UAAU,GAAG,EAAE,QAAQ,SAAS,CAAC,cAAe,cAAc,MAAM,QAAQ,KAAM;AAC3F;AAGO,SAAS,WAAW,MAAc,WAA2B;AAClE,SAAO,IAAI,eAAe,IAAI,CAAC,KAAK,cAAc,IAAI,SAAS,EAAE,CAAC;AACpE;AAGO,SAAS,UAAU,WAAmB,WAA4B;AACvE,SAAO,IAAI,UAAU,QAAQ,oBAAoB,IAAI,EAAE,QAAQ,SAAS,YAAY,KAAK,OAAO,CAAC;AACnG;AAGO,SAAS,QAAQ,MAAc,SAAyB;AAC7D,SAAO,GAAG,KAAK,QAAQ,QAAQ,EAAE,CAAC,IAAI,QAAQ,QAAQ,QAAQ,EAAE,CAAC;AACnE;AAGO,IAAM,oBAAoB;AAG1B,IAAM,wBAAwB;AAG9B,IAAM,kBAAkB;","names":[]}

package/dist/{chunk-PWNWSYI4.js → chunk-LYTJBMVK.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;
@@ -69,40 +80,16 @@ function findBlogsListing(pages, post) {
     (index) => listBlogPosts(pages, index, { drafts: false, stickyFirst: 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 listAnnouncements(pages, drafts) {
+  return pages.filter(isPost).filter((post) => post.post.announcement && (drafts || !post.post.draft)).sort(compareByDate);
 }
-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(/^\/+/, "")}`;
+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 });
+    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
@@ -211,6 +198,11 @@ var DEFAULT_LABELS = {
   allPosts: "All posts in {blog}",
   draft: "Draft",
   sticky: "Pinned",
+  announcement: "Announcement",
+  announcements: "Announcements",
+  noAnnouncements: "No announcements.",
+  announcementCount: "{n} announcements",
+  dismiss: "Dismiss",
   noPosts: "No posts yet.",
   undated: "Undated",
   tags: "Keywords",
@@ -390,12 +382,22 @@ function renderTags(tags, blogRoutePath) {
 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 renderBadges(post, context) {
+  const { draft, sticky, announcement } = post.post;
+  return [
+    draft && renderBadge("draft", context),
+    sticky && renderBadge("sticky", 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) {
@@ -424,12 +426,13 @@ function renderCard(post, context, index) {
   const modifiers = [
     post.post.sticky && "sticky",
     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)}>`,
     ...image ? block("vp-blog-card__image", `[![${alt}](${toMarkdownUrl(image)})](${toMarkdownUrl(link)})`) : [],
     '<div class="vp-blog-card__body">',
     ...block("vp-blog-card__title", toPageLink(post.post.title, post.routePath)),
@@ -442,8 +445,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)}></span>`;
   return `- ${marker}${date}${toPageLink(post.post.title, post.routePath)}${badges ? ` ${badges}` : ""}`;
 }
 function renderGroup(posts, index, context) {
@@ -518,7 +521,9 @@ function renderClientAttributes(index, context) {
     "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-no-announcements": labels.noAnnouncements
   };
   return Object.entries(attributes).map(([name, value]) => `${name}="${escapeHtml(value)}"`).join(" ");
 }
@@ -684,6 +689,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)),
@@ -701,6 +707,8 @@ function resolvePostData(data, content, fallbackTitle, options = {}) {
     scope: toScope(post.scope),
     sticky: 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),
@@ -1088,7 +1096,8 @@ export {
   isIndex,
   listBlogPosts,
   findBlogsListing,
-  joinUrl,
+  listAnnouncements,
+  findAnnouncementBlog,
   toPageUrl,
   toFeedPath,
   resolvePostImage,
@@ -1105,4 +1114,4 @@ export {
   hasWidget,
   blogMarkdown
 };
-//# sourceMappingURL=chunk-PWNWSYI4.js.map
+//# sourceMappingURL=chunk-LYTJBMVK.js.map