fix: path normalization, example correction, TS types, comments cleanup

.eslintignore

@@ -1 +1,2 @@
-test/fixtures
+test/fixtures
+lib

README.md

@@ -137,7 +137,7 @@ metalsmith
         defaults: {
           refs: {
             docs_index: 'file:./docs/index.html',
-            globalLinks: metalsmith.metadata().globalLinks
+            globalLinks: 'metadata:globalLinks'
           }
         }
       }

lib/index.d.ts

@@ -1,10 +1,14 @@
-import { Plugin } from 'metalsmith';
-
 export default refs;
 export type Options = {
-    key: string;
+    /**
+     * Limit ref substitution by glob pattern to a subset of files
+     */
+    pattern?: string | string[];
 };
 /**
- * A Metalsmith plugin to serve as a boilerplate for other core plugins
+ * A metalsmith plugin to refer to other files and global metadata from a file's refs property
+ *
+ * @param {Options} options
+ * @returns {import('metalsmith').Plugin}
  */
-declare function refs(options: Options): Plugin;
+declare function refs(options: Options): import('metalsmith').Plugin;

src/index.js

@@ -1,4 +1,4 @@
-import { relative, dirname, isAbsolute } from 'path'
+import { relative, dirname, isAbsolute, normalize } from 'path'
 import get from 'dlv'
 
 /**
@@ -34,7 +34,7 @@ function refs(options) {
     function srcRelPath(subdir, path) {
       if (isAbsolute(path)) path = path.slice(1)
       const referringPath = metalsmith.path(metalsmith.source(), subdir)
-      return relative(metalsmith.source(), metalsmith.path(referringPath, path))
+      return relative(metalsmith.source(), metalsmith.path(referringPath, normalize(path)))
     }
 
     const meta = metalsmith.metadata()
@@ -53,13 +53,9 @@ function refs(options) {
     })
 
     if (withRefs.length) debug('Processing refs for %s file(s)', withRefs.length)
-    else debug.warn('No files with "refs" defined".')
+    else debug.warn('No files with "refs" defined.')
 
     while (withRefs.length) {
-      /**
-       * @type {Object} file
-       * @property {Object<string, string>} file.refs
-       */
       const [path, file] = withRefs.shift()
 
       Object.entries(file.refs).forEach(([name, ref]) => {

test/index.js

@@ -49,7 +49,7 @@ describe('@metalsmith/refs', function () {
     equals(fixture('default/build'), fixture('default/expected'))
   })
 
-  it('should resolve absolute refs', async function () {
+  it('should resolve absolute refs to metalsmith.source()', async function () {
     await Metalsmith(fixture('absolute-refs')).env('DEBUG', process.env.DEBUG).use(plugin()).use(toJSON).build()
     equals(fixture('absolute-refs/build'), fixture('absolute-refs/expected'))
   })