@binarynoir/vitepress-blog 0.1.0 → 0.2.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. |
@@ -164,6 +164,38 @@ 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`.
+
 ## Blog pages
 
 A page with `blog-index` in its frontmatter lists posts. `blog-index: true` is a
@@ -333,32 +365,36 @@ 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',

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

@@ -104,12 +104,6 @@ function toUrlPath(routePath, cleanUrls) {
 function joinUrl(base, urlPath) {
   return `${base.replace(/\/+$/, "")}/${urlPath.replace(/^\/+/, "")}`;
 }
-function toIsoDate(date) {
-  return date.toISOString().slice(0, 10);
-}
-function formatDate(date, locale, format) {
-  return new Intl.DateTimeFormat(locale, { timeZone: "UTC", ...format }).format(date);
-}
 
 // src/feed.ts
 import { createHash } from "crypto";
@@ -208,7 +202,9 @@ ${lines.filter(Boolean).map((line) => `      ${line}`).join("\n")}
 // src/types.ts
 var DEFAULT_LABELS = {
   by: "By",
+  published: "Published",
   updated: "Updated",
+  dateTime: "{date} at {time}",
   readingTime: "{n} min read",
   newer: "Newer post",
   older: "Older post",
@@ -230,12 +226,118 @@ var DEFAULT_LABELS = {
 
 // src/render.ts
 import path2 from "path";
+
+// src/dates.ts
+var DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3})\d*)?)?)?\s*(Z|[+-]\d{2}:?\d{2})?$/i;
+function isTimeZone(timeZone) {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+var warnedZones = /* @__PURE__ */ new Set();
+function resolveTimeZone(timeZone) {
+  if (!timeZone) return "UTC";
+  if (isTimeZone(timeZone)) return timeZone;
+  if (!warnedZones.has(timeZone)) {
+    warnedZones.add(timeZone);
+    console.warn(
+      `[vitepress-blog] "${timeZone}" is not a time zone; using UTC. Use an IANA name such as "America/New_York".`
+    );
+  }
+  return "UTC";
+}
+var offsetFormats = /* @__PURE__ */ new Map();
+function zoneOffset(instant, timeZone) {
+  let format = offsetFormats.get(timeZone);
+  if (!format) {
+    format = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit"
+    });
+    offsetFormats.set(timeZone, format);
+  }
+  const parts = Object.fromEntries(format.formatToParts(instant).map(({ type, value }) => [type, Number(value)]));
+  const wall = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+  return wall - Math.floor(instant / 1e3) * 1e3;
+}
+function fromZonedTime(wall, timeZone) {
+  const first = wall - zoneOffset(wall, timeZone);
+  const second = wall - zoneOffset(first, timeZone);
+  return second;
+}
+function parsePostDate(value, timeZone = "UTC") {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return null;
+    const midnight = value.getUTCHours() === 0 && value.getUTCMinutes() === 0 && value.getUTCSeconds() === 0;
+    return { date: value, hasTime: !midnight };
+  }
+  if (typeof value !== "string") return null;
+  const match = DATE_TIME.exec(value.trim());
+  if (!match) return null;
+  const [, year, month, day, hour, minute, second = "0", millisecond = "0", offset] = match;
+  const hasTime = hour !== void 0;
+  const wall = Date.UTC(
+    Number(year),
+    Number(month) - 1,
+    Number(day),
+    hasTime ? Number(hour) : 0,
+    hasTime ? Number(minute) : 0,
+    Number(second),
+    Number(millisecond.padEnd(3, "0"))
+  );
+  const check = new Date(wall);
+  if (check.getUTCMonth() !== Number(month) - 1 || check.getUTCDate() !== Number(day)) return null;
+  if (!offset) return { date: new Date(fromZonedTime(wall, timeZone)), hasTime };
+  if (offset.toUpperCase() === "Z") return { date: new Date(wall), hasTime };
+  const sign = offset.startsWith("-") ? -1 : 1;
+  const digits = offset.slice(1).replace(":", "");
+  const minutes = Number(digits.slice(0, 2)) * 60 + Number(digits.slice(2));
+  return { date: new Date(wall - sign * minutes * 6e4), hasTime };
+}
+function formatPostDate({ date, hasTime }, display) {
+  const { locale, timeZone } = display;
+  const day = new Intl.DateTimeFormat(locale, { timeZone, ...display.dateFormat }).format(date);
+  if (!hasTime) return day;
+  const time = new Intl.DateTimeFormat(locale, { timeZone, ...display.timeFormat }).format(date);
+  return display.dateTime.replace("{date}", day).replace("{time}", time);
+}
+function toZonedIsoDate(date, timeZone) {
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat("en-US", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).formatToParts(date).map(({ type, value }) => [type, value])
+  );
+  return `${parts.year}-${parts.month}-${parts.day}`;
+}
+function toDateTimeAttribute({ date, hasTime }, timeZone) {
+  return hasTime ? date.toISOString() : toZonedIsoDate(date, timeZone);
+}
+function yearIn(date, timeZone) {
+  return Number(toZonedIsoDate(date, timeZone).slice(0, 4));
+}
+
+// src/render.ts
 var BLOG_POSTS_PLACEHOLDER = "<!-- blog-posts -->";
 function createRenderContext(options, pageDirectory, feeds = !!options.siteUrl) {
+  const locale = options.locale ?? "en-US";
+  const labels = { ...DEFAULT_LABELS, ...options.labels };
   return {
-    locale: options.locale ?? "en-US",
-    dateFormat: options.dateFormat ?? { dateStyle: "long" },
-    labels: { ...DEFAULT_LABELS, ...options.labels },
+    locale,
+    dates: {
+      locale,
+      timeZone: resolveTimeZone(options.timeZone),
+      dateFormat: options.dateFormat ?? { dateStyle: "long" },
+      timeFormat: options.timeFormat ?? { hour: "numeric", minute: "2-digit", timeZoneName: "short" },
+      dateTime: labels.dateTime
+    },
+    labels,
     pageDirectory,
     feeds
   };
@@ -257,8 +359,10 @@ function toImageSource(post, pageDirectory) {
   const relative = path2.relative(pageDirectory, absolute).split(path2.sep).join("/");
   return relative.startsWith(".") ? relative : `./${relative}`;
 }
-function renderTime(date, context) {
-  return `<time datetime="${toIsoDate(date)}">${escapeTemplateText(formatDate(date, context.locale, context.dateFormat))}</time>`;
+function renderTime(date, hasTime, context) {
+  const value = { date, hasTime };
+  const attribute = toDateTimeAttribute(value, context.dates.timeZone);
+  return `<time datetime="${attribute}">${escapeTemplateText(formatPostDate(value, context.dates))}</time>`;
 }
 function renderAuthor(author) {
   return author.url ? `[${escapeMarkdown(author.name)}](${toMarkdownUrl(author.url)})` : escapeMarkdown(author.name);
@@ -287,16 +391,19 @@ function toTagsAttribute(post) {
   return escapeHtml(post.post.tags.map((tag) => tag.toLowerCase()).join("|"));
 }
 function renderMeta(post, context, include) {
-  const { date, updated, readingMinutes, authors, draft, sticky } = post.post;
+  const { date, dateHasTime, updated, updatedHasTime, readingMinutes, authors, draft, sticky } = post.post;
   const parts = [];
   if (include.badges) {
     const badges = [draft && renderBadge("draft", context), sticky && renderBadge("sticky", context)];
     const shown = badges.filter(Boolean).join(" ");
     if (shown) parts.push(shown);
   }
-  if (date) parts.push(renderTime(date, context));
+  if (date) {
+    const time = renderTime(date, dateHasTime, context);
+    parts.push(include.updated ? `${escapeMarkdown(context.labels.published)} ${time}` : time);
+  }
   if (include.updated && updated && (!date || updated.getTime() !== date.getTime())) {
-    parts.push(`${escapeMarkdown(context.labels.updated)} ${renderTime(updated, context)}`);
+    parts.push(`${escapeMarkdown(context.labels.updated)} ${renderTime(updated, updatedHasTime, context)}`);
   }
   if (readingMinutes) parts.push(escapeMarkdown(fill(context.labels.readingTime, { n: String(readingMinutes) })));
   if (include.authors) {
@@ -334,7 +441,7 @@ function renderCard(post, context, index) {
   ];
 }
 function renderCompactItem(post, context) {
-  const date = post.post.date ? `${renderTime(post.post.date, 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>`;
   return `- ${marker}${date}${toPageLink(post.post.title, post.routePath)}${badges ? ` ${badges}` : ""}`;
@@ -359,7 +466,7 @@ function renderGroup(posts, index, context) {
 function renderYears(posts, index, context) {
   const years = /* @__PURE__ */ new Map();
   for (const post of posts) {
-    const year = post.post.date ? String(post.post.date.getUTCFullYear()) : context.labels.undated;
+    const year = post.post.date ? String(yearIn(post.post.date, context.dates.timeZone)) : context.labels.undated;
     years.set(year, [...years.get(year) ?? [], post]);
   }
   const lines = [];
@@ -510,12 +617,6 @@ function toStringList(value) {
   const values = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
   return values.map(toText).filter(Boolean);
 }
-function toDate(value) {
-  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
-  if (typeof value !== "string" && typeof value !== "number") return null;
-  const date = new Date(value);
-  return Number.isNaN(date.getTime()) ? null : date;
-}
 function toAuthor(value, options) {
   if (typeof value === "string") {
     const name2 = value.trim();
@@ -580,11 +681,16 @@ function resolvePostData(data, content, fallbackTitle, options = {}) {
   const stripTags = options.stripTags ?? true;
   const clean = (text) => stripTags ? stripTagSyntax(text) : text;
   const image = toRecord(pick("image"));
+  const timeZone = resolveTimeZone(options.timeZone);
+  const date = parsePostDate(pick("date"), timeZone);
+  const updated = parsePostDate(pick("updated"), timeZone);
   return {
     title: clean(toText(post.title) || toText(data.title) || readHeading(content)) || fallbackTitle,
     summary: clean(toText(post.summary) || toText(data.description) || readExcerpt(content)),
-    date: toDate(pick("date")),
-    updated: toDate(pick("updated")),
+    date: date?.date ?? null,
+    dateHasTime: date?.hasTime ?? false,
+    updated: updated?.date ?? null,
+    updatedHasTime: updated?.hasTime ?? false,
     image: toText(image.src) || toText(pick("image")),
     imageAlt: toText(image.alt) || toText(post.imageAlt) || toText(data.imageAlt),
     imageFit: (toText(image.fit) || toText(post.imageFit)) === "contain" ? "contain" : "cover",
@@ -714,7 +820,8 @@ function toOptionsKey(options) {
     options.stripTags,
     options.pageSize,
     options.stickyLimit,
-    options.rssLink
+    options.rssLink,
+    options.timeZone
   ]);
 }
 function indexBlogSource(sourceDirectory, options = {}, rewrites = {}) {
@@ -998,4 +1105,4 @@ export {
   hasWidget,
   blogMarkdown
 };
-//# sourceMappingURL=chunk-DICBXOTS.js.map
+//# sourceMappingURL=chunk-PWNWSYI4.js.map