metalsmith-collections-related: add filter options (#244)

Author: emmercm

package-lock.json

@@ -1,5 +1,10 @@
 # Changelog
 
+## v2.1.0 / 2025-11-27
+
+- Added the `filter` function option.
+- Added filtering of the `related_ignore` file metadata key.
+
 ## v2.0.0 / 2023-11-06
 
 - Converted to TypeScript, including type definitions.

packages/metalsmith-collections-related/CHANGELOG.md

@@ -80,14 +80,20 @@ which can be used with templating engines, such as with [`handlebars`](https://w
 {{/each}}
 ```
 
-## Options
+## Plugin options
 
 ### `pattern` (optional)
 
 Type: `string` Default: `"**/*"`
 
 A [`micromatch`](https://www.npmjs.com/package/micromatch) glob pattern to find input files.
 
+### `filter` (optional)
+
+Type: `(basePage: Metalsmith.File, relatedPage: Metalsmith.File, idx: number) => boolean`
+
+A function to filter out pages from a "base" page's list of related pages.
+
 ### `maxRelated` (optional)
 
 Type: `number` Default: `3`
@@ -131,6 +137,23 @@ Type: `object` Default:
 
 An object of [`sanitize-html`](https://www.npmjs.com/package/sanitize-html) options.
 
+## Metadata options
+
+### `related_ignore` (optional)
+
+Type: `boolean` Default: `false`
+
+If a file has a truthy `related_ignore` metadata value, it will be excluded from other files' related lists. These files will still have a related list calculated for them.
+
+Example:
+
+```markdown
+---
+related_ignore: true
+---
+This Markdown file won't appear in any other file's "related" list.
+```
+
 ## Changelog
 
 [Changelog](./CHANGELOG.md)

packages/metalsmith-collections-related/README.md

@@ -8,6 +8,7 @@ const { TfIdf } = natural;
 
 export interface Options {
   pattern?: string;
+  filter?: (basePage: Metalsmith.File, relatedPage: Metalsmith.File, idx: number) => boolean;
   maxRelated?: number;
   natural?: {
     minTfIdf?: number;
@@ -117,6 +118,12 @@ export default (options: Options = {}): Metalsmith.Plugin => {
             // Sort by filename ascending second
             return a.filename > b.filename ? 1 : -1;
           })
+          .filter((related) => !files[related.filename].related_ignore)
+          .filter((related, idx) =>
+            options.filter !== undefined
+              ? options.filter(files[filename], files[related.filename], idx)
+              : true,
+          )
           .slice(0, defaultedOptions.maxRelated)
           .map((related) => files[related.filename]);
 

packages/metalsmith-collections-related/index.ts

@@ -1,6 +1,6 @@
 {
   "name": "metalsmith-collections-related",
-  "version": "2.0.16",
+  "version": "2.1.0",
   "description": "A Metalsmith plugin to find related files within collections.",
   "keywords": [
     "metalsmith",

packages/metalsmith-collections-related/package.json

@@ -1,5 +1,5 @@
 A coppersmith, also known as a brazier, is a person who makes artifacts from copper and brass. Brass is an alloy of copper and zinc. The term redsmith is used for a tinsmith that uses tinsmithing tools and techniques to make copper items.
 
-/wikipedia/blacksmith.md
 /wikipedia/goldsmith.md
 /wikipedia/metalsmith.md
+/wikipedia/silversmith.md

packages/metalsmith-collections-related/test/fixtures/basic/expected/wikipedia/coppersmith.md

@@ -5,5 +5,5 @@ Goldsmiths must be skilled in forming metal through filing, soldering, sawing, f
 At least in Europe, goldsmiths increasingly performed many of the functions now regarded as part of banking, especially providing custody of valuable items and currency exchange, though they were usually restrained from lending at interest, which was regarded as usury.
 
 /wikipedia/metalsmith.md
-/wikipedia/blacksmith.md
 /wikipedia/tinsmith.md
+/wikipedia/coppersmith.md

packages/metalsmith-collections-related/test/fixtures/basic/expected/wikipedia/goldsmith.md

@@ -4,4 +4,4 @@ The prevalence of metalworking in the culture of recent centuries has led Smith
 
 /wikipedia/goldsmith.md
 /wikipedia/tinsmith.md
-/wikipedia/blacksmith.md
+/wikipedia/coppersmith.md

packages/metalsmith-collections-related/test/fixtures/basic/expected/wikipedia/metalsmith.md

@@ -1,5 +1,5 @@
 A silversmith is a metalworker who crafts objects from silver. The terms silversmith and goldsmith are not exactly synonyms as the techniques, training, history, and guilds are or were largely the same but the end product may vary greatly as may the scale of objects created.
 
-/wikipedia/blacksmith.md
 /wikipedia/goldsmith.md
 /wikipedia/coppersmith.md
+/wikipedia/metalsmith.md

packages/metalsmith-collections-related/test/fixtures/basic/expected/wikipedia/silversmith.md

@@ -2,6 +2,6 @@ A tinsmith, sometimes known as a tinner, tinker, tinman, or tinplate worker is a
 
 Unlike blacksmiths (who work mostly with hot metals), tinsmiths do the majority of their work on cold metal (although they might use a hearth to heat and help shape their raw materials). Tinsmiths fabricate items such as water pitchers, forks, spoons, and candle holders.
 
-/wikipedia/blacksmith.md
 /wikipedia/coppersmith.md
 /wikipedia/goldsmith.md
+/wikipedia/metalsmith.md