@binarynoir/vitepress-blog 0.1.1 → 0.3.0

package/README.md

@@ -127,8 +127,8 @@ with every default; an object sets its details.
 ---
 title: We launched
 blog:
-  date: 2026-10-01
-  updated: 2026-10-05
+  date: 2026-10-01 09:00
+  updated: 2026-10-05 16:30
   summary: Team A's first release is out.
   image: ./launch.png
   imageAlt: The release dashboard
@@ -144,8 +144,8 @@ blog:
 | --------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `title`         | the page's `title`, then its `#` heading   | Title in lists, feeds and social cards.                                                                                                                   |
 | `summary`       | the page's `description`, then first prose | One or two sentences for cards, feeds and `<meta name="description">`.                                                                                    |
-| `date`          | none                                       | Publication date. Posts are sorted newest first; undated posts go last.                                                                                   |
-| `updated`       | none                                       | Shown in the byline and used as the feed's last-updated time.                                                                                             |
+| `date`          | none                                       | When the post was published: a date, or a date and time. See [Dates and times](#dates-and-times). Newest first; undated posts go last.                    |
+| `updated`       | none                                       | When the post was last changed, in the same forms. The byline shows both: "Published … · Updated …". It is the feed's last-updated time.                  |
 | `image`         | none                                       | Card, social and feed image: a path relative to the post, a public path (`/cover.png`) or a URL. `{ src, alt, fit, position }` also works.                |
 | `imageAlt`      | `''`                                       | Alt text for the image.                                                                                                                                   |
 | `imageFit`      | `cover`                                    | How cards fit the image in their frame: `cover` crops it to fill the frame, `contain` shows all of it, letterboxed. Use `contain` for logos and diagrams. |
@@ -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.                                                                                                            |
@@ -164,6 +165,67 @@ Title, description, date, author(s), image and tags may also be written at the
 top level of the frontmatter, as other blog tools expect. A value under `blog`
 wins.
 
+### Dates and times
+
+`date` and `updated` take a date, or a date and a time, in any of these forms:
+
+| Written                     | Means                                       |
+| --------------------------- | ------------------------------------------- |
+| `2026-10-20`                | A day. Shows "October 20, 2026".            |
+| `2026-10-20 14:30`          | A day and a time, in the `timeZone` option. |
+| `2026-10-20T14:30:00`       | The same, with a `T` and seconds.           |
+| `2026-10-20T14:30:00-04:00` | An exact moment, with its offset from UTC.  |
+| `2026-10-20T18:30:00Z`      | An exact moment, in UTC.                    |
+
+```yaml
+blog:
+  date: 2026-10-20 14:30
+  updated: 2026-10-21 09:05
+```
+
+- **A time shows only when you give one.** A date alone is shown as a date,
+  never as "12:00 AM".
+- **Times without an offset are in the `timeZone` option**, `UTC` unless you
+  set one, so the same frontmatter means the same moment on every build
+  machine. Set `timeZone: 'America/New_York'` and write local times; daylight
+  saving is taken care of. Dates and times are also shown in that time zone.
+- **The byline tells readers both:** "Published October 20, 2026 at 2:30 PM
+  EDT · Updated October 21, 2026 at 9:05 AM EDT". Cards show the published
+  date alone.
+- **Posts on the same day sort by their times**, newest first, and a date
+  alone counts as the start of its day.
+- 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
@@ -238,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
@@ -333,38 +446,47 @@ link that copy. Public paths (`/cover.png`) and URLs are linked as they are.
 
 ## Options
 
-| Option           | Default                 | What it does                                                                                             |
-| ---------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- |
-| `siteUrl`        | `sitemap.hostname`      | Absolute URL of the published site, for feeds and social tags.                                           |
-| `authors`        | `{}`                    | Authors posts can name by key: `{ jane: { name, url, email } }` or `{ jane: 'Jane Doe' }`.               |
-| `defaultAuthor`  | none                    | Author for posts that don't name one.                                                                    |
-| `locale`         | `'en-US'`               | Locale for dates and author lists ("Jane and Sam").                                                      |
-| `dateFormat`     | `{ dateStyle: 'long' }` | `Intl.DateTimeFormat` options. Dates are shown in UTC.                                                   |
-| `wordsPerMinute` | `200`                   | For "5 min read". `0` hides reading time.                                                                |
-| `byline`         | `true`                  | Author, date and tags under each post's title.                                                           |
-| `cover`          | `false`                 | Each post's image under its byline.                                                                      |
-| `postNav`        | `true`                  | Newer and older post links at the end of each post.                                                      |
-| `drafts`         | `false`                 | List drafts, marked. Pass `process.env.NODE_ENV !== 'production'` for dev only.                          |
-| `stripTags`      | `true`                  | Remove [Markdown Tags](https://binarynoir.tech/plugins/markdown-tags/) syntax from titles and summaries. |
-| `feedLimit`      | `20`                    | Most posts in each feed.                                                                                 |
-| `imagesDir`      | `'blog-images'`         | Output folder for copied post images.                                                                    |
-| `pageSize`       | `10`                    | Posts per page on blog pages that don't set `pageSize`. `0` turns pages off.                             |
-| `stickyLimit`    | `0` (all)               | Most pinned sticky posts on blog pages that don't set `stickyLimit`.                                     |
-| `rssLink`        | `true`                  | A "Subscribe" RSS link on blog pages and blocks that don't set `rssLink`.                                |
-| `labels`         | English                 | Words the plugin writes, for translating. See below.                                                     |
+| Option           | Default                                                         | What it does                                                                                                          |
+| ---------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `siteUrl`        | `sitemap.hostname`                                              | Absolute URL of the published site, for feeds and social tags.                                                        |
+| `authors`        | `{}`                                                            | Authors posts can name by key: `{ jane: { name, url, email } }` or `{ jane: 'Jane Doe' }`.                            |
+| `defaultAuthor`  | none                                                            | Author for posts that don't name one.                                                                                 |
+| `locale`         | `'en-US'`                                                       | Locale for dates and author lists ("Jane and Sam").                                                                   |
+| `dateFormat`     | `{ dateStyle: 'long' }`                                         | `Intl.DateTimeFormat` options for dates.                                                                              |
+| `timeFormat`     | `{ hour: 'numeric', minute: '2-digit', timeZoneName: 'short' }` | `Intl.DateTimeFormat` options for times, as in "2:30 PM EDT". Only dates given with a time show one.                  |
+| `timeZone`       | `'UTC'`                                                         | The IANA time zone (`'America/New_York'`) that times without an offset are in, and that dates and times are shown in. |
+| `wordsPerMinute` | `200`                                                           | For "5 min read". `0` hides reading time.                                                                             |
+| `byline`         | `true`                                                          | Author, date and tags under each post's title.                                                                        |
+| `cover`          | `false`                                                         | Each post's image under its byline.                                                                                   |
+| `postNav`        | `true`                                                          | Newer and older post links at the end of each post.                                                                   |
+| `drafts`         | `false`                                                         | List drafts, marked. Pass `process.env.NODE_ENV !== 'production'` for dev only.                                       |
+| `stripTags`      | `true`                                                          | Remove [Markdown Tags](https://binarynoir.tech/plugins/markdown-tags/) syntax from titles and summaries.              |
+| `feedLimit`      | `20`                                                            | Most posts in each feed.                                                                                              |
+| `imagesDir`      | `'blog-images'`                                                 | Output folder for copied post images.                                                                                 |
+| `pageSize`       | `10`                                                            | Posts per page on blog pages that don't set `pageSize`. `0` turns pages off.                                          |
+| `stickyLimit`    | `0` (all)                                                       | Most pinned sticky posts on blog pages that don't set `stickyLimit`.                                                  |
+| `rssLink`        | `true`                                                          | A "Subscribe" RSS link on blog pages and blocks that don't set `rssLink`.                                             |
+| `labels`         | English                                                         | Words the plugin writes, for translating. See below.                                                                  |
 
 ```ts
 withBlog(config, {
   locale: 'de-DE',
   labels: {
     by: 'Von',
+    published: 'Veröffentlicht',
     updated: 'Aktualisiert',
+    dateTime: '{date} um {time}',
     readingTime: '{n} Min. Lesezeit',
     newer: 'Neuerer Beitrag',
     older: 'Älterer Beitrag',
     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',
@@ -385,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":[]}