@binarynoir/vitepress-blog 0.1.1 → 0.2.0

package/dist/{plugin-BjbV6nDK.d.cts → plugin-BlfpqyX4.d.cts}

@@ -16,8 +16,21 @@ interface BlogOptions {
     siteUrl?: string;
     /** Locale for dates in bylines and cards. Default: `'en-US'`. */
     locale?: string;
-    /** How dates are written. Default: `{ dateStyle: 'long' }`, in UTC. */
+    /** How dates are written. Default: `{ dateStyle: 'long' }`. */
     dateFormat?: Intl.DateTimeFormatOptions;
+    /**
+     * How times are written, for dates whose frontmatter gives one
+     * (`2026-10-20 14:30`). Default: `{ hour: 'numeric', minute: '2-digit', timeZoneName: 'short' }`,
+     * as in "2:30 PM EDT".
+     */
+    timeFormat?: Intl.DateTimeFormatOptions;
+    /**
+     * The time zone frontmatter times without an offset are in, and that every
+     * date and time is shown in: an IANA name such as `'America/New_York'`.
+     * A value with an offset (`2026-10-20T14:30:00-04:00`, `…Z`) is read as
+     * written. Default: `'UTC'`.
+     */
+    timeZone?: string;
     /** Reading speed for the "5 min read" estimate. `0` hides it. Default: `200`. */
     wordsPerMinute?: number;
     /** Add an author, date and tags line under each post's title. Default: `true`. */
@@ -68,8 +81,12 @@ interface BlogOptions {
 interface BlogLabels {
     /** Before the author names: "By Jane Doe". */
     by: string;
+    /** Before a post's `date` in its byline: "Published October 20, 2026". */
+    published: string;
     /** Before a post's `updated` date. */
     updated: string;
+    /** A date and its time: "{date} at {time}". */
+    dateTime: string;
     /** Reading time: "{n} min read". */
     readingTime: string;
     newer: string;
@@ -138,8 +155,14 @@ interface BlogIndexConfig {
 interface BlogPostData {
     title: string;
     summary: string;
+    /** When the post was published, from `date`. */
     date: Date | null;
+    /** Whether `date` gave a time, not just a day. */
+    dateHasTime: boolean;
+    /** When the post was last changed, from `updated`. */
     updated: Date | null;
+    /** Whether `updated` gave a time, not just a day. */
+    updatedHasTime: boolean;
     /** As written: a path relative to the post, a public path (`/x.png`) or a URL. */
     image: string;
     imageAlt: string;

package/dist/{plugin-BjbV6nDK.d.ts → plugin-BlfpqyX4.d.ts}

@@ -16,8 +16,21 @@ interface BlogOptions {
     siteUrl?: string;
     /** Locale for dates in bylines and cards. Default: `'en-US'`. */
     locale?: string;
-    /** How dates are written. Default: `{ dateStyle: 'long' }`, in UTC. */
+    /** How dates are written. Default: `{ dateStyle: 'long' }`. */
     dateFormat?: Intl.DateTimeFormatOptions;
+    /**
+     * How times are written, for dates whose frontmatter gives one
+     * (`2026-10-20 14:30`). Default: `{ hour: 'numeric', minute: '2-digit', timeZoneName: 'short' }`,
+     * as in "2:30 PM EDT".
+     */
+    timeFormat?: Intl.DateTimeFormatOptions;
+    /**
+     * The time zone frontmatter times without an offset are in, and that every
+     * date and time is shown in: an IANA name such as `'America/New_York'`.
+     * A value with an offset (`2026-10-20T14:30:00-04:00`, `…Z`) is read as
+     * written. Default: `'UTC'`.
+     */
+    timeZone?: string;
     /** Reading speed for the "5 min read" estimate. `0` hides it. Default: `200`. */
     wordsPerMinute?: number;
     /** Add an author, date and tags line under each post's title. Default: `true`. */
@@ -68,8 +81,12 @@ interface BlogOptions {
 interface BlogLabels {
     /** Before the author names: "By Jane Doe". */
     by: string;
+    /** Before a post's `date` in its byline: "Published October 20, 2026". */
+    published: string;
     /** Before a post's `updated` date. */
     updated: string;
+    /** A date and its time: "{date} at {time}". */
+    dateTime: string;
     /** Reading time: "{n} min read". */
     readingTime: string;
     newer: string;
@@ -138,8 +155,14 @@ interface BlogIndexConfig {
 interface BlogPostData {
     title: string;
     summary: string;
+    /** When the post was published, from `date`. */
     date: Date | null;
+    /** Whether `date` gave a time, not just a day. */
+    dateHasTime: boolean;
+    /** When the post was last changed, from `updated`. */
     updated: Date | null;
+    /** Whether `updated` gave a time, not just a day. */
+    updatedHasTime: boolean;
     /** As written: a path relative to the post, a public path (`/x.png`) or a URL. */
     image: string;
     imageAlt: string;

package/dist/vitepress.cjs

@@ -117,6 +117,104 @@ function findBlogsListing(pages, post) {
 // src/frontmatter.ts
 var import_node_path = __toESM(require("path"), 1);
 var import_yaml = require("yaml");
+
+// 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/frontmatter.ts
 var POST_FRONTMATTER_KEY = "blog";
 var INDEX_FRONTMATTER_KEY = "blog-index";
 var FRONTMATTER = /^---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|$)/;
@@ -155,12 +253,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();
@@ -225,11 +317,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",
@@ -333,12 +430,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
 function toAbsoluteUrl(urlPath, site) {
@@ -440,7 +531,9 @@ var import_node_path3 = __toESM(require("path"), 1);
 // 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",
@@ -463,10 +556,18 @@ var DEFAULT_LABELS = {
 // 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
   };
@@ -488,8 +589,10 @@ function toImageSource(post, pageDirectory) {
   const relative = import_node_path3.default.relative(pageDirectory, absolute).split(import_node_path3.default.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);
@@ -518,16 +621,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) {
@@ -565,7 +671,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}` : ""}`;
@@ -590,7 +696,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 = [];
@@ -765,7 +871,8 @@ function toOptionsKey(options) {
     options.stripTags,
     options.pageSize,
     options.stickyLimit,
-    options.rssLink
+    options.rssLink,
+    options.timeZone
   ]);
 }
 function indexBlogSource(sourceDirectory, options = {}, rewrites = {}) {