Refs initial repo setup & implementation

.eslintignore

@@ -0,0 +1 @@
+test/fixtures

.release-it.json

@@ -17,8 +17,8 @@
   },
   "github": {
     "release": true,
-    "releaseName": "@metalsmith/~core-plugin~ ${version}",
+    "releaseName": "@metalsmith/refs ${version}",
     "tokenRef": "GITHUB_TOKEN",
-    "assets": ["metalsmith-~core-plugin~-${version}.tgz"]
+    "assets": ["metalsmith-refs-${version}.tgz"]
   }
 }

README.md

@@ -1,106 +1,185 @@
-_Note: This is a template repository_
+# @metalsmith/refs
 
-Usage:
-
-1. Click "Use this template", see also https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template, fill in new plugin details
-2. Search and replace all `core-plugin` `CorePlugin` and `corePlugin` matches with the name of the plugin
-3. Change description in package.json & match in repo description
-4. Remove this text
-
----
-
-# @metalsmith/~core-plugin~
-
-A metalsmith plugin to...
+A metalsmith plugin to easily refer to other files and global metadata from `file.refs`
 
 [![metalsmith: core plugin][metalsmith-badge]][metalsmith-url]
 [![npm: version][npm-badge]][npm-url]
 [![ci: build][ci-badge]][ci-url]
 [![code coverage][codecov-badge]][codecov-url]
-[![license: MIT][license-badge]][license-url]
+[![license: LGPL][license-badge]][license-url]
 
 ## Features
 
-An optional features section (if there are many), or an extended description of the core plugin
+- Gives your files a default, but customizable _`id`entity_ matching its relative file path
+- Substitutes a file's `refs` keypaths with their target file- or metadata values
+- Allows tracing a file's manipulations via its `id` property
+- Batch assign references with [@metalsmith/default-values](https://github.com/metalsmith/default-values)
 
 ## Installation
 
 NPM:
 
 ```
-npm install @metalsmith/~core-plugin~
+npm install @metalsmith/refs
 ```
 
 Yarn:
 
 ```
-yarn add @metalsmith/~core-plugin~
+yarn add @metalsmith/refs
 ```
 
 ## Usage
 
-Pass `@metalsmith/~core-plugin~` to `metalsmith.use` :
+Pass `@metalsmith/refs` to `metalsmith.use` :
 
 ```js
-import ~corePlugin~ from '@metalsmith/~core-plugin~'
+import refs from '@metalsmith/refs'
+import layouts from '@metalsmith/layouts
 
-metalsmith.use(~corePlugin~()) // defaults
-metalsmith.use(~corePlugin~({  // explicit defaults
-  ...
+metalsmith.use(refs()) // defaults
+metalsmith.use(refs({  // explicit defaults
+  pattern: '**'
 }))
+
+metalsmith.use(layouts({ pattern: '**/*.html' })) // defaults
 ```
 
-### Options
+Now you can, say, reference child documentation pages in the index `src/docs/index.html`:
 
-Optional section with list or table of options, if the plugin has a lot of options
+```yaml
+---
+id: docs_index
+refs:
+  # relative refs will be resolved vs the current file
+  getting_started: file:./getting-started/index.html
+  # absolute refs will be resolved vs metalsmith.source()
+  usage_guide: file:/docs/usage-guide/index.html
+---
+```
 
-### Specific usage example
+Refs are defined in a `protocol:path` format. As a shortcut, not specifying the `protocol:` part will default to `file:`.
 
-Document a first specific usage example, the title can be "Achieve x by doing y"
+When @metalsmith/refs runs, it will substitute the refs with the actual files:
 
-### Specific usage example
+```js
+{
+  'docs/index.html': {
+    id: 'docs_index',
+    refs: {
+      getting_started: {
+        id: 'docs/getting-started/index.html'
+        contents: Buffer.from('...'),
+        stats: {...}
+      },
+      usage_guide: {
+        id: 'docs/usage-guide/index.html'
+        contents: Buffer.from('...'),
+        stats: {...}
+      }
+    }
+  }
+}
+```
+
+The references are _references_, and not _clones_ of the targets they refer to, i.e. they will stay in sync when other plugins alter them later.
+
+As the example above shows, @metalsmith/refs will also add an `id` property to each processed file, unless you define an [explicit id](#custom-ids). By default the `id` is the file's path relative to metalsmith.source(), and with backslashes converted to forward slashes for cross-platform compatibility.
 
-Document a second specific usage example, the title can be "Achieve x by doing y"
+### Plugin order
+
+It is advised to use this plugin at the start of your build chain. Why? If you used plugins like [@metalsmith/permalinks](https://github.com/metalsmith/permalinks) that change the file's path before this plugin, the `id` property will not match the source path of the file.
+
+Using @metalsmith/refs at the start of your plugin chain gives you an easy way to _trace_ file transforms by other plugins.
+
+### Custom ids
+
+You can define an id property before @metalsmith/refs runs, and it will not be overwritten. In the example above, the getting-started and usage-guide pages could refer to the index with the `id:` protocol:
+
+```yaml
+---
+refs:
+  docs_home: id:docs_index
+---
+```
+
+This is useful if you wish to decouple a file's identity from its path on disk and to avoid having to commit a lot of small changes when/if you plan to reorganize source files.
+
+### Reference global metadata
+
+Metalsmith.metadata() keys can be referenced with the `metadata:` protocol, e.g.:
+
+`docs/index.html`
+
+```yaml
+---
+refs:
+  navigation: metadata:navigation
+  articles: metadata:collections.articles
+---
+```
+
+As the example demonstrates `dot.delimited.keypaths` are also supported.
+
+Referencing the entire `metalsmith.metadata()` object is not possible. Plugins like [@metalsmith/in-place](https://github.com/metalsmith/in-place) or [@metalsmith/layouts](https://github.com/metalsmith/layouts) already allow access to the global metadata in their render contexts.
+
+### Batch references by filepath
+
+Use [@metalsmith/default-values](https://github.com/metalsmith/default-values) before @metalsmith/refs to automatically assign refs by glob patterns:
+
+```js
+metalsmith
+  .use(
+    defaultValues([
+      {
+        pattern: 'docs/*/*.html',
+        defaults: {
+          refs: {
+            docs_index: 'file:./docs/index.html',
+            globalLinks: metalsmith.metadata().globalLinks
+          }
+        }
+      }
+    ])
+  )
+  .use(refs())
+```
 
 ### Debug
 
-To enable debug logs, set the `DEBUG` environment variable to `@metalsmith/~core_plugin~*`:
+To enable debug logs, set the `DEBUG` environment variable to `@metalsmith/refs*`:
 
 ```js
-metalsmith.env('DEBUG', '@metalsmith/~core_plugin~*')
+metalsmith.env('DEBUG', '@metalsmith/refs*')
 ```
 
 Alternatively you can set `DEBUG` to `@metalsmith/*` to debug all Metalsmith core plugins.
 
 ### CLI usage
 
-To use this plugin with the Metalsmith CLI, add `@metalsmith/~core-plugin~` to the `plugins` key in your `metalsmith.json` file:
+To use this plugin with the Metalsmith CLI, add `@metalsmith/refs` to the `plugins` key in your `metalsmith.json` file:
 
 ```json
 {
   "plugins": [
     {
-      "@metalsmith/~core-plugin~": {}
+      "@metalsmith/refs": {}
     }
   ]
 }
 ```
 
-## Credits (optional)
-
-Special thanks to ... for ...
-
 ## License
 
 [MIT](LICENSE)
 
-[npm-badge]: https://img.shields.io/npm/v/@metalsmith/~core-plugin~.svg
-[npm-url]: https://www.npmjs.com/package/@metalsmith/~core-plugin~
-[ci-badge]: https://github.com/metalsmith/~core-plugin~/actions/workflows/test.yml/badge.svg
-[ci-url]: https://github.com/metalsmith/~core-plugin~/actions/workflows/test.yml
+[npm-badge]: https://img.shields.io/npm/v/@metalsmith/refs.svg
+[npm-url]: https://www.npmjs.com/package/@metalsmith/refs
+[ci-badge]: https://github.com/metalsmith/refs/actions/workflows/test.yml/badge.svg
+[ci-url]: https://github.com/metalsmith/refs/actions/workflows/test.yml
 [metalsmith-badge]: https://img.shields.io/badge/metalsmith-core_plugin-green.svg?longCache=true
 [metalsmith-url]: https://metalsmith.io
-[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/~core-plugin~
-[codecov-url]: https://coveralls.io/github/metalsmith/~core-plugin~
-[license-badge]: https://img.shields.io/github/license/metalsmith/~core-plugin~
+[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/refs
+[codecov-url]: https://coveralls.io/github/metalsmith/refs
+[license-badge]: https://img.shields.io/github/license/metalsmith/refs
 [license-url]: LICENSE

lib/index.d.ts

@@ -1,10 +1,10 @@
 import { Plugin } from 'metalsmith';
 
-export default corePlugin;
+export default refs;
 export type Options = {
     key: string;
 };
 /**
  * A Metalsmith plugin to serve as a boilerplate for other core plugins
  */
-declare function corePlugin(options: Options): Plugin;
+declare function refs(options: Options): Plugin;

package.json

@@ -1,10 +1,10 @@
 {
-  "name": "@metalsmith/~core-plugin~",
-  "private": true,
+  "name": "@metalsmith/refs",
   "version": "0.1.0",
-  "description": "A Metalsmith plugin to ...",
+  "description": "A metalsmith plugin to refer to other files and global metadata from a file's refs property",
   "keywords": [
-    "~core-plugin~",
+    "reference",
+    "metadata",
     "metalsmith-plugin",
     "metalsmith",
     "static-site"
@@ -20,7 +20,7 @@
   "types": "lib/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/metalsmith/~core-plugin~.git"
+    "url": "git+https://github.com/metalsmith/refs.git"
   },
   "files": [
     "lib",
@@ -33,11 +33,12 @@
   "author": "Kevin Van Lierde (https://webketje.com)",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/metalsmith/~core-plugin~/issues"
+    "url": "https://github.com/metalsmith/refs/issues"
   },
-  "homepage": "https://github.com/metalsmith/~core-plugin~#readme",
+  "homepage": "https://github.com/metalsmith/refs#readme",
   "dependencies": {
-    "debug": "^4.3.4"
+    "debug": "^4.3.4",
+    "dlv": "^1.1.3"
   },
   "devDependencies": {
     "assert-dir-equal": "^1.1.0",
@@ -69,7 +70,7 @@
     "test": "c8 mocha"
   },
   "engines": {
-    "node": ">=12.17.0 <13.0.0-0||>=13.2.0"
+    "node": ">=14.14.0"
   },
   "publishConfig": {
     "access": "public"