nuxt-content-assets 0.5.1

package/README.md

@@ -0,0 +1,276 @@
+# 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]
+
+## Overview
+
+Nuxt Content Assets enables locally-located assets in your [Nuxt Content](https://content.nuxtjs.org/) folder:
+
+```
++- content
+    +- posts
+        +- 2023-01-01
+            +- index.md
+            +- media
+                +- featured.png
+                +- mountains.jpg
+                +- seaside.mp4
+```
+
+In your documents, simply reference assets using relative paths:
+
+```markdown
+---
+title: Summer Holiday
+featured: media/featured.png
+---
+
+I loved being in the mountains.
+
+![mountains](media/mountains.png)
+
+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
+
+## Demo
+
+To run the demo online, go to:
+
+- https://stackblitz.com/github/davestewart/nuxt-content-assets?file=demo%2Fapp.vue
+
+You can browse the demo files in:
+
+- .https://github.com/davestewart/nuxt-content-assets/tree/main/demo
+
+To run the demo locally, clone the application and from the root, run:
+
+```
+npm run demo
+```
+
+## Setup
+
+Install the dependency:
+
+```bash
+npm install nuxt-content-assets
+```
+
+Configure `nuxt.config.ts`:
+
+```js
+export default defineNuxtConfig({
+  modules: [
+    'nuxt-content-relative-assets', // make sure to add before content!
+    '@nuxt/content',
+  ]
+})
+```
+
+Run the dev server or build and 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. 
+
+Here's how it works:
+
+- 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
+
+Right now, if you change any assets, you will need to re-run the dev server / build.
+
+### Supported formats
+
+The following file formats are supported out of the box:
+
+| Type   | Extensions                                                              |
+|--------|-------------------------------------------------------------------------|
+| Images | `png`, `jpg`, `jpeg`, `gif`, `svg`, `webp`                              |
+| 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.
+
+### Images
+
+The module [optionally](#image-attributes) writes `width` and `height` attributes to the generated HTML:
+
+```html
+<img src="..." width="640" height="480">
+```
+
+This locks the aspect ratio of the image preventing content jumps.
+
+If you use custom [ProseImg](https://content.nuxtjs.org/api/components/prose) components, you can even grab these values using the Vue `$attrs` property:
+
+```vue
+<template>
+  <div class="image">
+    <img :src="$attrs.src" :style="`aspect-ratio:${$attrs.width}/${$attrs.height}`" />
+  </div>
+</template>
+
+<script>
+export default {
+  inheritAttrs: false
+}
+</script>
+```
+
+See the [Demo](demo/components/_content/ProseImg.vue) for an example.
+
+## Configuration
+
+The module **doesn't require** any configuration, but you can tweak the following settings:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  'content-assets': {
+    // where to generate and serve the assets from
+    output: 'assets/content/[path]/[file]',
+    
+    // add additional extensions
+    additionalExtensions: 'html',
+    
+    // completely replace supported extensions
+    extensions: 'png jpg',
+    
+    // add image width and height
+    imageAttrs: true,
+    
+    // print debug messages to the console
+    debug: true,
+  }
+})
+```
+
+### Output
+
+The output path can be customised using a template string:
+
+```
+assets/img/content/[path]/[name][extname]
+```
+
+The first part of the path should be public root-relative folder:
+
+```
+assets/img/content
+```
+
+The optional second part of the path indicates specific placement of each image: 
+
+| Token       | Description                                | Example            |
+|-------------|--------------------------------------------|--------------------|
+| `[folder]`  | The relative folder of the file            | `posts/2023-01-01` |
+| `[file]`    | The full filename of the file              | `featured.jpg`     |
+| `[name]`    | The name of the file without the extension | `featured`         |
+| `[hash]`    | A hash of the absolute source path         | `9M00N4l9A0`       |
+| `[extname]` | The full extension with the dot            | `.jpg`             |
+| `[ext]`     | The extension without the dot              | `jpg`              |
+
+For example:
+
+| Template                             | Output                                             |
+|--------------------------------------|----------------------------------------------------|
+| `assets/img/content/[folder]/[file]` | `assets/img/content/posts/2023-01-01/featured.jpg` |
+| `assets/img/[name]-[hash].[ext]`     | `assets/img/featured-9M00N4l9A0.jpg`               |
+| `content/[hash].[ext]`               | `content/9M00N4l9A0.jpg`                           |
+
+Note that the module defaults to all files in a single folder:
+
+```
+/assets/content/[name]-[hash].[ext]
+```
+
+### Extensions
+
+You can add or replace supported extensions if you need to:
+
+To add extensions, use `additionalExtensions`:
+
+```ts
+{
+  additionalExtensions: 'html' // add support for html
+}
+```
+
+To completely replace supported extensions, use `extensions`:
+
+```ts
+{
+	extensions: 'png jpg' // serve png and jpg files only
+}
+```
+
+### Image attributes
+
+The module automatically adds `width` and `height` attributes to images.
+
+Opt out of this by passing `false`:
+
+```ts
+{
+  imageAttrs: false
+}
+```
+
+## Development
+
+Should you wish to develop the project, the scripts are:
+
+```bash
+# install dependencies
+npm install
+
+# generate type stubs
+npm run dev:prepare
+
+# develop with the demo
+npm run dev
+
+# build the demo
+npm run dev:build
+
+# run eslint
+npm run lint
+
+# run vitest
+npm run test
+npm run test:watch
+
+# release new version
+npm run release
+```
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-content-assets/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
+[npm-version-href]: https://npmjs.com/package/nuxt-content-assets
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-content-assets.svg?style=flat&colorA=18181B&colorB=28CF8D
+[npm-downloads-href]: https://npmjs.com/package/nuxt-content-assets
+
+[license-src]: https://img.shields.io/npm/l/nuxt-content-assets.svg?style=flat&colorA=18181B&colorB=28CF8D
+[license-href]: https://npmjs.com/package/nuxt-content-assets
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.ts

@@ -0,0 +1,12 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    output?: string;
+    additionalExtensions?: string;
+    extensions?: string;
+    imageAttrs?: boolean;
+    debug?: boolean;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions>;
+
+export { ModuleOptions, _default as default };

package/dist/module.json

@@ -0,0 +1,5 @@
+{
+  "name": "content-assets",
+  "configKey": "content-assets",
+  "version": "0.5.1"
+}

package/dist/module.mjs

@@ -0,0 +1,180 @@
+import { createResolver, defineNuxtModule, addTemplate } from '@nuxt/kit';
+import getImageSize from 'image-size';
+import glob from 'glob';
+import * as Fs from 'fs';
+import * as Path from 'path';
+import Path__default from 'path';
+import { hash } from 'ohash';
+
+function log(...data) {
+  console.info(`[${name}]`, ...data);
+}
+
+function matchWords(value) {
+  return value.match(/\w+/g) || [];
+}
+function isImage(path) {
+  const ext = Path__default.extname(path).substring(1);
+  return imageExtensions.includes(ext);
+}
+function interpolatePattern(pattern, src, dir, warn = false) {
+  return Path__default.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;
+  }));
+}
+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 name = "content-assets";
+const defaults = {
+  assetsDir: "assets/content",
+  assetsPattern: "[name]-[hash].[ext]"
+};
+const imageExtensions = matchWords("png jpg jpeg gif svg webp ico");
+const mediaExtensions = matchWords("mp3 m4a wav mp4 mov webm ogg avi flv avchd");
+const fileExtensions = matchWords("pdf doc docx xls xlsx ppt pptx odp key");
+const extensions = [
+  ...imageExtensions,
+  ...mediaExtensions,
+  ...fileExtensions
+];
+
+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 resolve = createResolver(import.meta.url).resolve;
+const module = defineNuxtModule({
+  meta: {
+    name
+  },
+  defaults: {
+    output: `${defaults.assetsDir}/${defaults.assetsPattern}`,
+    extensions: "",
+    additionalExtensions: "",
+    imageAttrs: true,
+    debug: false
+  },
+  setup(options, nuxt) {
+    var _a;
+    const pluginPath = resolve("./runtime/server") + "/plugins/plugin";
+    const buildPath = nuxt.options.buildDir;
+    const cachePath = Path.resolve(buildPath, "content-assets");
+    if (options.debug) {
+      log("Removing cache folders...");
+    }
+    Fs.rmSync(Path.join(buildPath, "content-cache"), { recursive: true, force: true });
+    Fs.rmSync(cachePath, { recursive: true, force: true });
+    const sources = nuxt.options._layers.map((layer) => layer.config?.content?.sources).reduce((output2, sources2) => {
+      if (sources2) {
+        Object.assign(output2, getSources(sources2));
+      }
+      return output2;
+    }, {});
+    if (Object.keys(sources).length === 0 || !sources.content) {
+      const content = nuxt.options.srcDir + "/content";
+      if (Fs.existsSync(content)) {
+        sources.content = content;
+      }
+    }
+    const output = options.output || defaults.assetsDir;
+    const matches = output.match(/([^[]+)(.*)?/);
+    const assetsDir = matches ? matches[1] : defaults.assetsDir;
+    const assetsPattern = (matches ? matches[2] : "") || defaults.assetsPattern;
+    interpolatePattern(assetsPattern, "", "", true);
+    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;
+      if (options.imageAttrs && isImage(src)) {
+        const size = getImageSize(src);
+        width = size.width;
+        height = size.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 };
+    }
+    const publicFolder = Path.join(cachePath, assetsDir);
+    const sourceFolders = Object.values(sources);
+    const assets = {};
+    sourceFolders.forEach((folder) => {
+      const pattern = `${folder}/**/*.{${extensions.join(",")}}`;
+      const paths = glob.globSync(pattern);
+      paths.forEach((src) => {
+        const config = getAssetConfig(assetsPattern, src, folder);
+        nuxt.options.content.ignores.push(config.id);
+        assets[src] = config;
+      });
+    });
+    nuxt.hook("build:before", function() {
+      Fs.mkdirSync(publicFolder, { recursive: true });
+      if (options.debug) {
+        const paths = Object.keys(assets).map((key) => "   - " + assets[key].id.replaceAll(":", "/"));
+        log(`Copying ${Object.keys(assets).length} assets:
+
+${paths.join("\n")}
+`);
+      }
+      Object.keys(assets).forEach((src) => {
+        const { trg } = assets[src];
+        const trgFolder = Path.dirname(trg);
+        Fs.mkdirSync(trgFolder, { recursive: true });
+        Fs.copyFileSync(src, trg);
+      });
+    });
+    const virtualConfig = [
+      `export const assets = ${JSON.stringify(assets)}`,
+      `export const sources = ${JSON.stringify(sources)}`
+    ].join("\n");
+    nuxt.options.alias[`#${name}`] = addTemplate({
+      filename: `${name}.mjs`,
+      getContents: () => virtualConfig
+    }).dst;
+    nuxt.hook("nitro:config", async (config) => {
+      config.plugins || (config.plugins = []);
+      config.plugins.push(pluginPath);
+      config.virtual || (config.virtual = {});
+      config.virtual[`#${name}`] = virtualConfig;
+      config.publicAssets || (config.publicAssets = []);
+      config.publicAssets.push({
+        dir: cachePath
+        // maxAge: 60 * 60 * 24 * 365 // 1 year
+      });
+    });
+  }
+});
+
+export { module as default };

package/dist/runtime/server/plugins/plugin.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/plugins/plugin.mjs

@@ -0,0 +1,52 @@
+import Path from "path";
+import { visit } from "unist-util-visit";
+import { assets, sources } from "#content-assets";
+import { tags } from "../../../config";
+import { isValidAsset, walk } from "../../../utils";
+function getDocPath(id) {
+  const parts = id.split(":");
+  const key = parts.shift();
+  const relPath = parts.join("/");
+  const absBase = sources[key];
+  return Path.join(absBase, relPath);
+}
+function getAsset(absDoc, relAsset) {
+  const absAsset = Path.join(Path.dirname(absDoc), relAsset);
+  return assets[absAsset] || {};
+}
+export default defineNitroPlugin(async (nitroApp) => {
+  nitroApp.hooks.hook("content:file:afterParse", async (file) => {
+    if (file._id.endsWith(".md")) {
+      const absDoc = getDocPath(file._id);
+      const filter = (value, key) => !(String(key).startsWith("_") || key === "body");
+      walk(file, (value, parent, key) => {
+        if (isValidAsset(value)) {
+          const { rel } = getAsset(absDoc, value);
+          if (rel) {
+            parent[key] = rel;
+          }
+        }
+      }, filter);
+      visit(file.body, (n) => tags.includes(n.tag), (node) => {
+        if (node.props.src) {
+          const { rel, width, height } = getAsset(absDoc, node.props.src);
+          if (rel) {
+            node.props.src = rel;
+          }
+          if (width && height) {
+            node.props.width = width;
+            node.props.height = height;
+          }
+        } else if (node.tag === "a") {
+          if (node.props.href) {
+            const { rel } = getAsset(absDoc, node.props.href);
+            if (rel) {
+              node.props.href = rel;
+              node.props.target = "_blank";
+            }
+          }
+        }
+      });
+    }
+  });
+});

package/dist/types.d.ts

@@ -0,0 +1,10 @@
+
+import { ModuleOptions } from './module'
+
+declare module '@nuxt/schema' {
+  interface NuxtConfig { ['content-assets']?: Partial<ModuleOptions> }
+  interface NuxtOptions { ['content-assets']?: ModuleOptions }
+}
+
+
+export { ModuleOptions, default } from './module'

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "nuxt-content-assets",
+  "version": "0.5.1",
+  "description": "Enable locally-located assets in Nuxt Content",
+  "repository": "davestewart/nuxt-content-assets",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/module.mjs",
+      "require": "./dist/module.cjs"
+    }
+  },
+  "main": "./dist/module.cjs",
+  "types": "./dist/types.d.ts",
+  "files": [
+    "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",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^3.3.2",
+    "glob": "^9.3.2",
+    "image-size": "^1.0.2",
+    "ohash": "^1.0.0",
+    "unist-util-visit": "^4.1.2"
+  },
+  "peerDependencies": {
+    "@nuxt/content": "latest"
+  },
+  "devDependencies": {
+    "@nuxt/content": "latest",
+    "@nuxt/eslint-config": "^0.1.1",
+    "@nuxt/module-builder": "^0.2.1",
+    "@nuxt/schema": "^3.3.2",
+    "@nuxt/test-utils": "^3.3.2",
+    "changelogen": "^0.5.1",
+    "eslint": "^8.36.0",
+    "nuxt": "^3.3.2",
+    "vitest": "^0.29.7"
+  }
+}