@docusaurus/plugin-content-blog 4.0.0-canary-6817 → 4.0.0-canary-6820

package/lib/blogUtils.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { TagsFile } from '@docusaurus/utils';
-import type { LoadContext } from '@docusaurus/types';
+import type { LoadContext, VcsConfig } from '@docusaurus/types';
 import type { AuthorsMap, PluginOptions, BlogPost, BlogTags, BlogPaginated } from '@docusaurus/plugin-content-blog';
 import type { BlogContentPaths } from './types';
 export declare function truncate(fileString: string, truncateMarker: RegExp): string;
@@ -35,6 +35,13 @@ type ParsedBlogFileName = {
     slug: string;
 };
 export declare function parseBlogFileName(blogSourceRelative: string): ParsedBlogFileName;
+export declare function parseFrontMatterDate(date: string | Date): Date;
+export declare function getBlogPostDate({ frontMatterDate, filenameDate, filePath, vcs, }: {
+    frontMatterDate?: string | Date;
+    filenameDate?: Date;
+    filePath: string;
+    vcs: VcsConfig;
+}): Promise<Date>;
 export declare function generateBlogPosts(contentPaths: BlogContentPaths, context: LoadContext, options: PluginOptions, tagsFile: TagsFile | null, authorsMap?: AuthorsMap): Promise<BlogPost[]>;
 export declare function applyProcessBlogPosts({ blogPosts, processBlogPosts, }: {
     blogPosts: BlogPost[];

package/lib/blogUtils.js

@@ -12,6 +12,8 @@ exports.paginateBlogPosts = paginateBlogPosts;
 exports.shouldBeListed = shouldBeListed;
 exports.getBlogTags = getBlogTags;
 exports.parseBlogFileName = parseBlogFileName;
+exports.parseFrontMatterDate = parseFrontMatterDate;
+exports.getBlogPostDate = getBlogPostDate;
 exports.generateBlogPosts = generateBlogPosts;
 exports.applyProcessBlogPosts = applyProcessBlogPosts;
 const tslib_1 = require("tslib");
@@ -110,6 +112,34 @@ function parseBlogFileName(blogSourceRelative) {
     const slug = `/${text}`;
     return { date: undefined, text, slug };
 }
+function parseFrontMatterDate(date) {
+    if (typeof date === 'string') {
+        const dateString = date.trim();
+        // Detect a timezone suffix in the time portion, not the date's day/year.
+        // YAML timestamps allow tabs and short offsets; also accept ISO +/-HHMM.
+        // https://yaml.org/type/timestamp.html
+        // This detects a timezone, not date validity (already checked by Joi).
+        const hasTimeZone = /[t \t]\d.*(?:z|[+-]\d{1,2}(?::?\d{2})?)$/i.test(dateString);
+        // Treat dates without an explicit timezone as UTC.
+        return new Date(hasTimeZone ? dateString : `${dateString}Z`);
+    }
+    // Custom front matter parsers can still return Date objects.
+    return date;
+}
+async function getBlogPostDate({ frontMatterDate, filenameDate, filePath, vcs, }) {
+    // Prefer front matter, then the filename, then the file creation date.
+    if (frontMatterDate) {
+        return parseFrontMatterDate(frontMatterDate);
+    }
+    else if (filenameDate) {
+        return filenameDate;
+    }
+    const result = await vcs.getFileCreationInfo(filePath);
+    if (result == null) {
+        return (await fs_extra_1.default.stat(filePath)).birthtime;
+    }
+    return new Date(result.timestamp);
+}
 async function parseBlogPostMarkdownFile({ filePath, parseFrontMatter, }) {
     const fileContent = await fs_extra_1.default.readFile(filePath, 'utf-8');
     try {
@@ -151,26 +181,12 @@ async function processBlogSourceFile(blogSourceRelative, contentPaths, context,
         logger_1.default.warn `name=${'id'} header option is deprecated in path=${blogSourceRelative} file. Please use name=${'slug'} option instead.`;
     }
     const parsedBlogFileName = parseBlogFileName(blogSourceRelative);
-    async function getDate() {
-        // Prefer user-defined date.
-        if (frontMatter.date) {
-            if (typeof frontMatter.date === 'string') {
-                // Always treat dates as UTC by adding the `Z`
-                return new Date(`${frontMatter.date}Z`);
-            }
-            // YAML only converts YYYY-MM-DD to dates and leaves others as strings.
-            return frontMatter.date;
-        }
-        else if (parsedBlogFileName.date) {
-            return parsedBlogFileName.date;
-        }
-        const result = await vcs.getFileCreationInfo(blogSourceAbsolute);
-        if (result == null) {
-            return (await fs_extra_1.default.stat(blogSourceAbsolute)).birthtime;
-        }
-        return new Date(result.timestamp);
-    }
-    const date = await getDate();
+    const date = await getBlogPostDate({
+        frontMatterDate: frontMatter.date,
+        filenameDate: parsedBlogFileName.date,
+        filePath: blogSourceAbsolute,
+        vcs,
+    });
     const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text;
     const description = frontMatter.description ?? excerpt ?? '';
     const slug = frontMatter.slug ?? parsedBlogFileName.slug;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "4.0.0-canary-6817",
+  "version": "4.0.0-canary-6820",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -31,15 +31,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "4.0.0-canary-6817",
-    "@docusaurus/logger": "4.0.0-canary-6817",
-    "@docusaurus/mdx-loader": "4.0.0-canary-6817",
-    "@docusaurus/module-type-aliases": "4.0.0-canary-6817",
-    "@docusaurus/theme-common": "4.0.0-canary-6817",
-    "@docusaurus/types": "4.0.0-canary-6817",
-    "@docusaurus/utils": "4.0.0-canary-6817",
-    "@docusaurus/utils-common": "4.0.0-canary-6817",
-    "@docusaurus/utils-validation": "4.0.0-canary-6817",
+    "@docusaurus/core": "4.0.0-canary-6820",
+    "@docusaurus/logger": "4.0.0-canary-6820",
+    "@docusaurus/mdx-loader": "4.0.0-canary-6820",
+    "@docusaurus/module-type-aliases": "4.0.0-canary-6820",
+    "@docusaurus/theme-common": "4.0.0-canary-6820",
+    "@docusaurus/types": "4.0.0-canary-6820",
+    "@docusaurus/utils": "4.0.0-canary-6820",
+    "@docusaurus/utils-common": "4.0.0-canary-6820",
+    "@docusaurus/utils-validation": "4.0.0-canary-6820",
     "cheerio": "^1.2.0",
     "combine-promises": "^1.2.0",
     "feed": "^5.2.1",
@@ -57,11 +57,11 @@
     "react-dom": "^19.3.0"
   },
   "engines": {
-    "node": ">=24.14"
+    "node": ">=26.9"
   },
   "devDependencies": {
     "@total-typescript/shoehorn": "^0.1.2",
     "tree-node-cli": "^3.0.0"
   },
-  "gitHead": "38c20529ba3a20243f31ce7a56764e969bf9ba7b"
+  "gitHead": "548b203e01abc1df60907285520e3b000a9af3eb"
 }

package/src/blogUtils.ts

@@ -32,7 +32,7 @@ import {getBlogPostAuthors} from './authors';
 import {reportAuthorsProblems} from './authorsProblems';
 import {calculateReadingTime} from './readingTime';
 import type {TagsFile} from '@docusaurus/utils';
-import type {LoadContext, ParseFrontMatter} from '@docusaurus/types';
+import type {LoadContext, ParseFrontMatter, VcsConfig} from '@docusaurus/types';
 import type {
   AuthorsMap,
   PluginOptions,
@@ -184,6 +184,48 @@ export function parseBlogFileName(
   return {date: undefined, text, slug};
 }
 
+export function parseFrontMatterDate(date: string | Date): Date {
+  if (typeof date === 'string') {
+    const dateString = date.trim();
+    // Detect a timezone suffix in the time portion, not the date's day/year.
+    // YAML timestamps allow tabs and short offsets; also accept ISO +/-HHMM.
+    // https://yaml.org/type/timestamp.html
+    // This detects a timezone, not date validity (already checked by Joi).
+    const hasTimeZone = /[t \t]\d.*(?:z|[+-]\d{1,2}(?::?\d{2})?)$/i.test(
+      dateString,
+    );
+    // Treat dates without an explicit timezone as UTC.
+    return new Date(hasTimeZone ? dateString : `${dateString}Z`);
+  }
+  // Custom front matter parsers can still return Date objects.
+  return date;
+}
+
+export async function getBlogPostDate({
+  frontMatterDate,
+  filenameDate,
+  filePath,
+  vcs,
+}: {
+  frontMatterDate?: string | Date;
+  filenameDate?: Date;
+  filePath: string;
+  vcs: VcsConfig;
+}): Promise<Date> {
+  // Prefer front matter, then the filename, then the file creation date.
+  if (frontMatterDate) {
+    return parseFrontMatterDate(frontMatterDate);
+  } else if (filenameDate) {
+    return filenameDate;
+  }
+
+  const result = await vcs.getFileCreationInfo(filePath);
+  if (result == null) {
+    return (await fs.stat(filePath)).birthtime;
+  }
+  return new Date(result.timestamp);
+}
+
 async function parseBlogPostMarkdownFile({
   filePath,
   parseFrontMatter,
@@ -273,27 +315,12 @@ async function processBlogSourceFile(
 
   const parsedBlogFileName = parseBlogFileName(blogSourceRelative);
 
-  async function getDate(): Promise<Date> {
-    // Prefer user-defined date.
-    if (frontMatter.date) {
-      if (typeof frontMatter.date === 'string') {
-        // Always treat dates as UTC by adding the `Z`
-        return new Date(`${frontMatter.date}Z`);
-      }
-      // YAML only converts YYYY-MM-DD to dates and leaves others as strings.
-      return frontMatter.date;
-    } else if (parsedBlogFileName.date) {
-      return parsedBlogFileName.date;
-    }
-
-    const result = await vcs.getFileCreationInfo(blogSourceAbsolute);
-    if (result == null) {
-      return (await fs.stat(blogSourceAbsolute)).birthtime;
-    }
-    return new Date(result.timestamp);
-  }
-
-  const date = await getDate();
+  const date = await getBlogPostDate({
+    frontMatterDate: frontMatter.date,
+    filenameDate: parsedBlogFileName.date,
+    filePath: blogSourceAbsolute,
+    vcs,
+  });
 
   const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text;
   const description = frontMatter.description ?? excerpt ?? '';