Documents 'hidden' feature for custom date formatting function, adds …

…date-fn test

README.md

@@ -266,6 +266,20 @@ Starting from v3 `@metalsmith/permalinks` no longer uses moment.js. A subset of
 Tokens marked with (\*) use the [Node.js Intl API](https://nodejs.org/api/intl.html) which is not available by default in every Node.js distribution.  
 The `date` option can be a string of date-formatting tokens and will default to `en-US` for the locale, or an object in the format `{ format: 'YYYY', locale: 'en-US' }`. However, if your Node.js distribution does not have support for the Intl API, or the locale you specified is missing, the build will throw an error.
 
+If you need more customization you can also pass a date formatting function:
+
+```js
+metalsmith.use(
+  permalinks({
+    pattern: ':date',
+    // will result in sun/jan/01/2024/index.html for date 2024-01-01
+    date(value) {
+      return value.toDateString().toLowerCase().replace(/\W/g, '/')
+    }
+  })
+)
+```
+
 #### Slug options
 
 You can finetune how a pattern is processed by providing custom [slug](https://developer.mozilla.org/en-US/docs/Glossary/Slug) options.

lib/index.d.ts

@@ -35,6 +35,7 @@ export type SlugifyOptions = {
     trim: boolean;
 };
 export type slugFunction = (filepath: string) => string;
+export type dateFunction = (date: Date) => string;
 /**
  * Linkset definition
  */
@@ -67,10 +68,10 @@ export type Linkset = {
      */
     slug?: SlugifyOptions | slugFunction;
     /**
-     * [Date format string](https://github.com/metalsmith/permalinks#dates) to transform Date link parts into, defaults to `YYYY/MM/DD`.
+     * [Date format string](https://github.com/metalsmith/permalinks#dates) to transform Date link parts into, or a custom date formatting function. Defaults to `YYYY/MM/DD`.
      * @default 'YYYY/MM/DD'
      */
-    date?: string;
+    date?: string | dateFunction;
 };
 /**
  * `@metalsmith/permalinks` options & default linkset

src/index.js

@@ -48,6 +48,12 @@ const dupeHandlers = {
  * @returns {string} slug
  */
 
+/**
+ * @callback dateFunction
+ * @param {Date} date
+ * @returns {string} formattedDate
+ */
+
 /**
  * Linkset definition
  *
@@ -57,15 +63,15 @@ const dupeHandlers = {
  * will be used to match files when at least one `key:value` pair matches, and transform their permalinks according to the rules in this linkset.
  * @property {string} pattern A permalink pattern to transform file paths into, e.g. `blog/:date/:title`
  * @property {SlugifyOptions|slugFunction} [slug] [Slugify options](https://github.com/simov/slugify) or a custom slug function of the form `(pathpart) => string`
- * @property {string} [date='YYYY/MM/DD'] [Date format string](https://github.com/metalsmith/permalinks/#date-formatting) to transform Date link parts into, defaults to `YYYY/MM/DD`.
+ * @property {string|dateFunction} [date='YYYY/MM/DD'] [Date format string](https://github.com/metalsmith/permalinks/#date-formatting) to transform Date link parts into, or a custom date formatting function. Defaults to `YYYY/MM/DD`.
  */
 
 /**
  * `@metalsmith/permalinks` options & default linkset
  *
  * @typedef {Object} Options
  * @property {string} [pattern=':dirname?/:basename'] A permalink pattern to transform file paths into, e.g. `blog/:date/:title`. Default is `:dirname?/:basename`.
- * @property {string} [date='YYYY/MM/DD'] [Date format string](https://github.com/metalsmith/permalinks/#date-formatting) to transform Date link parts into, defaults to `YYYY/MM/DD`.
+ * @property {string} [date='YYYY/MM/DD'] [Date format string](https://github.com/metalsmith/permalinks/#date-formatting) to transform Date link parts into, or a custom date formatting function. Defaults to `YYYY/MM/DD`.
  * @property {string} [directoryIndex='index.html'] Basename of the permalinked file (default: `index.html`)
  * @property {boolean} [trailingSlash=false] Whether a trailing `/` should be added to the `file.permalink` property. Useful to avoid redirects on servers which do not have a built-in rewrite module enabled.
  * @property {'error'|'index'|'overwrite'|Function} [duplicates='error'] How to handle duplicate target URI's.

test/fixtures/date-fn/expected/index.html

@@ -0,0 +1 @@
+other

test/fixtures/date-fn/expected/sun/jan/01/2012/index.html

@@ -0,0 +1,2 @@
+
+one

test/fixtures/date-fn/src/index.html

@@ -0,0 +1 @@
+other

test/fixtures/date-fn/src/one.html

@@ -0,0 +1,6 @@
+---
+title: One Post
+date: 2012-01-01
+---
+
+one

test/index.js

@@ -60,6 +60,16 @@ const fixtures = [
       date: 'YYYY/MM'
     }
   },
+  {
+    message: 'should format a date with a custom function',
+    folder: 'date-fn',
+    options: {
+      pattern: ':date?',
+      date(v) {
+        return v.toDateString().toLowerCase().replace(/\W/g, '/')
+      }
+    }
+  },
   {
     message: 'should format a linkset date with a custom formatter',
     folder: 'linkset-custom-date',