nuxt-content-assets 0.5.2 → 0.6.0

package/README.md

@@ -1,12 +1,16 @@
 # Nuxt Content Assets
 
-> Enable locally-located assets in Nuxt Content
-
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
+> Enable locally-located assets in Nuxt Content
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/davestewart/nuxt-content-assets/main/demo/content/splash.png" alt="Nuxt Content Assets logo">
+</p>
+
 ## Overview
 
 Nuxt Content Assets enables locally-located assets in your [Nuxt Content](https://content.nuxtjs.org/) folder:
@@ -22,7 +26,7 @@ Nuxt Content Assets enables locally-located assets in your [Nuxt Content](https:
                 +- seaside.mp4
 ```
 
-In your documents, simply reference assets using relative paths:
+In your documents, reference assets with relative paths:
 
 ```markdown
 ---
@@ -39,11 +43,7 @@ Almost as much as being in the sea!
 <video src="media/seaside.mp4"></video>
 ```
 
-The module:
-
-- supports configurable image, media and file types
-- supports appropriate HTML tags
-- converts markdown and frontmatter content
+That's it!
 
 ## Demo
 
@@ -80,26 +80,65 @@ export default defineNuxtConfig({
 })
 ```
 
-Run the dev server or build and assets should now be served alongside markdown content.
+Run the dev server or build and local assets should now be served alongside markdown content.
 
 ## Usage
 
 ### Overview
 
-Once the build or dev server is running, paths should be rewritten and assets served automatically. 
+Use relative paths anywhere within your documents:
 
-Here's how it works:
+```mdx
+![image](image.jpg)
+<video src="media/video.mp4" />
+```
 
-- the module scans content folders for assets
-- these are copied to a temporary build folder
-- matching relative paths in markdown are updated
-- Nitro serves the assets from the new location
+Relative paths are defined by anything not starting with a slash or `http`, for example:
+
+```
+image.jpg
+images/featured.png
+../assets/cv.pdf
+```
+
+Note that only specific tags and attributes are targeted:
+
+```html
+<img src="...">
+<video src="...">
+<audio src="...">
+<source src="...">
+<embed src="...">
+<iframe src="...">
+<a href="...">
+```
+
+However, you can use relative paths in frontmatter:
+
+```mdx
+---
+title: Portfolio Item 1
+images:
+  - images/image-1.jpg
+  - images/image-2.jpg
+  - images/image-3.jpg
+---
+```
+
+Then pass these to components like so:
+
+```markdown
+::gallery{:images="images"}
+::
+```
 
-Right now, if you change any assets, you will need to re-run the dev server / build.
+> Note: to pass size hints in frontmatter, set the `imageSize` configuration option to `'url'`
 
-### Supported formats
+See the [Demo](demo/content/recipes/index.md) for an example.
 
-The following file formats are supported out of the box:
+### Supported assets
+
+The following file extensions are targeted by default:
 
 | Type   | Extensions                                                              |
 |--------|-------------------------------------------------------------------------|
@@ -107,31 +146,22 @@ The following file formats are supported out of the box:
 | Media  | `mp3`, `m4a`, `wav`, `mp4`, `mov`, `webm`, `ogg`, `avi`, `flv`, `avchd` |
 | Files  | `pdf`, `doc`, `docx`, `xls`, `xlsx`, `ppt`, `pptx`, `odp`, `key`        |
 
-See the [configuration](#output) section for more options.
+See the [configuration](#output) section to modify or change this list, and the [Demo](demo/nuxt.config.ts) for an example.
 
 ### Images
 
-The module can [optionally](#image-attributes) write `width`, `height` and `aspect-ratio` information to generated `<img>` tags:
+The module can prevent content jumps by optionally writing image size information to generated `<img>` tags:
 
 ```html
-<img src="..." width="640" height="480" style="aspect-ratio:640/480">
+<img src="/image.jpg?width=640&height=480" width="640" height="480" style="aspect-ratio:640/480">
 ```
 
-This can prevent content jumps on page load. If you add `attributes` only, include the following CSS in your app:
-
-```css
-img {
-  max-width: 100%;
-  height: auto;
-}
-```
-
-If you use custom [ProseImg](https://content.nuxtjs.org/api/components/prose) components, you can use these values in your own markup:
+If you use custom [ProseImg](https://content.nuxtjs.org/api/components/prose) components, you can pass these values to your own markup:
 
 ```vue
 <template>
   <span class="image">
-    <img :src="$attrs.src" :style="$attrs.style" />
+    <img :src="$attrs.src" :width="$attrs.width" :height="$attrs.height" />
   </span>
 </template>
 
@@ -142,11 +172,22 @@ export default {
 </script>
 ```
 
-See the [Demo](demo/components/_content/ProseImg.vue) for an example.
+See the [configuration](#image-size) section to add this, and the [Demo](demo/components/_content/ProseImg.vue) for an example.
+
+### Build
+
+Once the dev server or build is running, the following happens:
+
+- the module scans content folders for assets
+- these are copied to a temporary build folder
+- matching relative paths markdown are rewritten
+- Nitro serves the assets from the new location
+
+If you change any assets, you'll need to re-run the dev server / build (there is an [issue](https://github.com/davestewart/nuxt-content-assets/issues/1) open to look at this).
 
 ## Configuration
 
-The module **doesn't require** any configuration, but you can tweak the following settings:
+The module will run happily without configuration, but should you need to:
 
 ```ts
 // nuxt.config.ts
@@ -162,7 +203,7 @@ export default defineNuxtConfig({
     extensions: 'png jpg',
     
     // use aspect-ratio rather than attributes
-    imageSize: 'ratio',
+    imageSize: 'style',
     
     // print debug messages to the console
     debug: true,
@@ -229,9 +270,9 @@ To replace extensions, use `extensions`:
 }
 ```
 
-### Image attributes
+### Image size
 
-You can add image size hints to the generated images.
+You can add image size hints to the generated images via attributes, style, or the URL.
 
 To add `style` aspect-ratio:
 
@@ -249,7 +290,34 @@ To add `width` and `height` attributes:
 }
 ```
 
-You can even add both if you need to.
+If you add `attributes` only, include the following CSS in your app:
+
+```css
+img {
+  max-width: 100%;
+  height: auto;
+}
+```
+
+To pass size hints as parameters in the URL (frontmatter only, see [Demo](demo/components/content/Gallery.vue)):
+
+```ts
+{
+  imageSize: 'url'
+}
+```
+
+Note that you can one, some or all keywords, i.e. `attrs url`.
+
+### Debug
+
+If you want to see what the module does as it runs, set `debug` to true:
+
+```ts
+{
+  debug: true
+}
+```
 
 ## Development
 

package/dist/module.json

@@ -1,5 +1,8 @@
 {
   "name": "nuxt-content-assets",
   "configKey": "content-assets",
-  "version": "0.5.2"
+  "compatibility": {
+    "nuxt": "^3.0.0"
+  },
+  "version": "0.6.0"
 }

package/dist/module.mjs

@@ -6,17 +6,8 @@ import * as Path from 'path';
 import Path__default from 'path';
 import { hash } from 'ohash';
 
-function getSources(sources) {
-  return Object.keys(sources).reduce((output, key) => {
-    const source = sources[key];
-    if (source) {
-      const { driver, base } = source;
-      if (driver === "fs") {
-        output[key] = base;
-      }
-    }
-    return output;
-  }, {});
+function matchWords(value) {
+  return typeof value === "string" ? value.match(/\w+/g) || [] : [];
 }
 
 const defaults = {
@@ -32,6 +23,24 @@ const extensions = [
   ...fileExtensions
 ];
 
+function isImage(path) {
+  const ext = Path__default.extname(path).substring(1);
+  return imageExtensions.includes(ext);
+}
+
+function getSources(sources) {
+  return Object.keys(sources).reduce((output, key) => {
+    const source = sources[key];
+    if (source) {
+      const { driver, base } = source;
+      if (driver === "fs") {
+        output[key] = base;
+      }
+    }
+    return output;
+  }, {});
+}
+
 const moduleName = "nuxt-content-assets";
 const moduleKey = "content-assets";
 
@@ -39,13 +48,14 @@ function log(...data) {
   console.info(`[${moduleKey}]`, ...data);
 }
 
-function matchWords(value) {
-  return value.match(/\w+/g) || [];
-}
-function isImage(path) {
-  const ext = Path__default.extname(path).substring(1);
-  return imageExtensions.includes(ext);
-}
+const replacers = {
+  folder: (src, dir) => Path__default.dirname(src.replace(dir, "")),
+  file: (src) => Path__default.basename(src),
+  name: (src) => Path__default.basename(src, Path__default.extname(src)),
+  extname: (src) => Path__default.extname(src),
+  ext: (src) => Path__default.extname(src).substring(1),
+  hash: (src) => hash({ src })
+};
 function interpolatePattern(pattern, src, dir, warn = false) {
   return Path__default.join(pattern.replace(/\[\w+]/g, (match) => {
     const name = match.substring(1, match.length - 1);
@@ -59,20 +69,15 @@ function interpolatePattern(pattern, src, dir, warn = false) {
     return match;
   }));
 }
-const replacers = {
-  folder: (src, dir) => Path__default.dirname(src.replace(dir, "")),
-  file: (src) => Path__default.basename(src),
-  name: (src) => Path__default.basename(src, Path__default.extname(src)),
-  extname: (src) => Path__default.extname(src),
-  ext: (src) => Path__default.extname(src).substring(1),
-  hash: (src) => hash({ src })
-};
 
 const resolve = createResolver(import.meta.url).resolve;
 const module = defineNuxtModule({
   meta: {
     name: moduleName,
-    configKey: moduleKey
+    configKey: moduleKey,
+    compatibility: {
+      nuxt: "^3.0.0"
+    }
   },
   defaults: {
     output: `${defaults.assetsDir}/${defaults.assetsPattern}`,
@@ -108,37 +113,42 @@ const module = defineNuxtModule({
     const assetsDir = matches ? matches[1] : defaults.assetsDir;
     const assetsPattern = (matches ? matches[2] : "") || defaults.assetsPattern;
     interpolatePattern(assetsPattern, "", "", true);
+    const imageFlags = matchWords(options.imageSize);
     if (options.extensions?.trim()) {
       extensions.splice(0, extensions.length, ...matchWords(options.extensions));
     } else if (options.additionalExtensions) {
       extensions.push(...matchWords(options.additionalExtensions));
     }
-    if (nuxt.options.content) {
-      (_a = nuxt.options.content).ignores || (_a.ignores = []);
-    }
     function getAssetConfig(pattern, src, dir) {
       let width = void 0;
       let height = void 0;
-      let ratio = "";
-      if (options.imageSize && isImage(src)) {
+      let ratio = void 0;
+      let query = void 0;
+      if (imageFlags.length && isImage(src)) {
         const size = getImageSize(src);
-        if (options.imageSize.includes("style")) {
+        if (imageFlags.includes("style")) {
           ratio = `${size.width}/${size.height}`;
         }
-        if (options.imageSize.includes("attrs")) {
+        if (imageFlags.includes("attrs")) {
           width = size.width;
           height = size.height;
         }
+        if (imageFlags.includes("url")) {
+          query = `?width=${width}&height=${height}`;
+        }
       }
       const id = Path.join(Path.basename(dir), Path.relative(dir, src)).replaceAll("/", ":");
       const file = interpolatePattern(pattern, src, dir);
       const trg = Path.join(cachePath, assetsDir, file);
       const rel = Path.join("/", assetsDir, file);
-      return { id, file, trg, rel, width, height, ratio };
+      return { id, file, trg, rel, width, height, ratio, query };
     }
     const publicFolder = Path.join(cachePath, assetsDir);
     const sourceFolders = Object.values(sources);
     const assets = {};
+    if (nuxt.options.content) {
+      (_a = nuxt.options.content).ignores || (_a.ignores = []);
+    }
     sourceFolders.forEach((folder) => {
       const pattern = `${folder}/**/*.{${extensions.join(",")}}`;
       const paths = glob.globSync(pattern);

package/dist/runtime/options.d.ts

@@ -2,8 +2,8 @@ export declare const defaults: {
     assetsDir: string;
     assetsPattern: string;
 };
-export declare const imageExtensions: RegExpMatchArray | [];
-export declare const mediaExtensions: RegExpMatchArray | [];
-export declare const fileExtensions: RegExpMatchArray | [];
+export declare const imageExtensions: string[];
+export declare const mediaExtensions: string[];
+export declare const fileExtensions: string[];
 export declare const extensions: string[];
 export declare const tags: string[];

package/dist/runtime/options.mjs

@@ -1,4 +1,4 @@
-import { matchWords } from "./utils/assets.mjs";
+import { matchWords } from "./utils/config.mjs";
 export const defaults = {
   assetsDir: "assets/content",
   assetsPattern: "[folder]/[file]"

package/dist/runtime/plugin.mjs

@@ -21,9 +21,9 @@ export default defineNitroPlugin(async (nitroApp) => {
       const filter = (value, key) => !(String(key).startsWith("_") || key === "body");
       walk(file, (value, parent, key) => {
         if (isValidAsset(value)) {
-          const { rel } = getAsset(absDoc, value);
+          const { rel, query } = getAsset(absDoc, value);
           if (rel) {
-            parent[key] = rel;
+            parent[key] = rel + (query || "");
           }
         }
       }, filter);

package/dist/runtime/utils/assets.d.ts

@@ -1,7 +1,3 @@
-/**
- * Get matched words from a string
- */
-export declare function matchWords(value: string): RegExpMatchArray | [];
 /**
  * Test path to be relative
  */
@@ -18,16 +14,3 @@ export declare function isAsset(path: string): boolean;
  * Test if value is a valid asset
  */
 export declare function isValidAsset(value?: string): boolean;
-/**
- * Interpolate assets path pattern
- *
- * @param pattern   A path pattern with tokens
- * @param src       The absolute path to a src asset
- * @param dir       The absolute path to its containing folder
- * @param warn      An optional flag to warn for unknown tokens
- */
-export declare function interpolatePattern(pattern: string, src: string, dir: string, warn?: boolean): any;
-/**
- * Hash of replacer functions
- */
-export declare const replacers: Record<string, Function>;

package/dist/runtime/utils/assets.mjs

@@ -1,10 +1,5 @@
 import Path from "path";
-import { hash as ohash } from "ohash";
 import { extensions, imageExtensions } from "../options.mjs";
-import { log } from "./debug.mjs";
-export function matchWords(value) {
-  return value.match(/\w+/g) || [];
-}
 export function isRelative(path) {
   return !(path.startsWith("http") || Path.isAbsolute(path));
 }
@@ -19,24 +14,3 @@ export function isAsset(path) {
 export function isValidAsset(value) {
   return typeof value === "string" && isAsset(value) && isRelative(value);
 }
-export function interpolatePattern(pattern, src, dir, warn = false) {
-  return Path.join(pattern.replace(/\[\w+]/g, (match) => {
-    const name = match.substring(1, match.length - 1);
-    const fn = replacers[name];
-    if (fn) {
-      return fn(src, dir);
-    }
-    if (warn) {
-      log(`Unknown output token ${match}`, true);
-    }
-    return match;
-  }));
-}
-export const replacers = {
-  folder: (src, dir) => Path.dirname(src.replace(dir, "")),
-  file: (src) => Path.basename(src),
-  name: (src) => Path.basename(src, Path.extname(src)),
-  extname: (src) => Path.extname(src),
-  ext: (src) => Path.extname(src).substring(1),
-  hash: (src) => ohash({ src })
-};

package/dist/runtime/utils/config.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Get matched words from a string
+ */
+export declare function matchWords(value?: string): string[];

package/dist/runtime/utils/config.mjs

@@ -0,0 +1,3 @@
+export function matchWords(value) {
+  return typeof value === "string" ? value.match(/\w+/g) || [] : [];
+}

package/dist/runtime/utils/debug.d.ts

@@ -1,2 +1,3 @@
 export declare function log(...data: any[]): void;
 export declare function warn(...data: any[]): void;
+export declare function dump(name: string, data: any): void;

package/dist/runtime/utils/debug.mjs

@@ -1,3 +1,5 @@
+import Path from "path";
+import Fs from "fs";
 import { moduleKey } from "../../config";
 export function log(...data) {
   console.info(`[${moduleKey}]`, ...data);
@@ -5,3 +7,10 @@ export function log(...data) {
 export function warn(...data) {
   console.warn(`[${moduleKey}]`, ...data);
 }
+export function dump(name, data) {
+  const path = `debug/${name}.json`;
+  const folder = Path.dirname(path);
+  log(`Dumping "${path}"`);
+  Fs.mkdirSync(folder, { recursive: true });
+  Fs.writeFileSync(path, JSON.stringify(data, null, "  "), { encoding: "utf8" });
+}

package/dist/runtime/utils/index.d.ts

@@ -1,4 +1,6 @@
-export * from './content';
-export * from './object';
 export * from './assets';
+export * from './config';
+export * from './content';
 export * from './debug';
+export * from './object';
+export * from './paths';

package/dist/runtime/utils/index.mjs

@@ -1,4 +1,6 @@
-export * from "./content.mjs";
-export * from "./object.mjs";
 export * from "./assets.mjs";
+export * from "./config.mjs";
+export * from "./content.mjs";
 export * from "./debug.mjs";
+export * from "./object.mjs";
+export * from "./paths.mjs";

package/dist/runtime/utils/paths.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Interpolate assets path pattern
+ *
+ * @param pattern   A path pattern with tokens
+ * @param src       The absolute path to a src asset
+ * @param dir       The absolute path to its containing folder
+ * @param warn      An optional flag to warn for unknown tokens
+ */
+export declare function interpolatePattern(pattern: string, src: string, dir: string, warn?: boolean): string;

package/dist/runtime/utils/paths.mjs

@@ -0,0 +1,24 @@
+import Path from "path";
+import { hash } from "ohash";
+import { log } from "./debug.mjs";
+const replacers = {
+  folder: (src, dir) => Path.dirname(src.replace(dir, "")),
+  file: (src) => Path.basename(src),
+  name: (src) => Path.basename(src, Path.extname(src)),
+  extname: (src) => Path.extname(src),
+  ext: (src) => Path.extname(src).substring(1),
+  hash: (src) => hash({ src })
+};
+export function interpolatePattern(pattern, src, dir, warn = false) {
+  return Path.join(pattern.replace(/\[\w+]/g, (match) => {
+    const name = match.substring(1, match.length - 1);
+    const fn = replacers[name];
+    if (fn) {
+      return fn(src, dir);
+    }
+    if (warn) {
+      log(`Unknown output token ${match}`, true);
+    }
+    return match;
+  }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-content-assets",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Enable locally-located assets in Nuxt Content",
   "repository": "davestewart/nuxt-content-assets",
   "license": "MIT",
@@ -18,11 +18,13 @@
     "dist"
   ],
   "scripts": {
-    "prepack": "nuxt-module-build",
     "dev": "nuxi dev demo",
     "dev:build": "nuxi build demo",
     "dev:prepare": "nuxt-module-build --stub && nuxi prepare demo",
-    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "build": "nuxt-module-build",
+    "release": "npm run lint && npm run test && npm run build && npm publish && git push --follow-tags",
+    "release:dry": "npm run lint && npm run test && npm run build && npm publish --dry-run",
+    "release:old": "npm run lint && npm run test && npm run build && changelogen --release && npm publish && git push --follow-tags",
     "lint": "eslint .",
     "test": "vitest run",
     "test:watch": "vitest watch"
@@ -48,4 +50,4 @@
     "nuxt": "^3.3.2",
     "vitest": "^0.29.7"
   }
-}
+}