nuxt-content-assets 0.7.0 → 0.9.0-alpha

package/README.md

@@ -13,7 +13,7 @@
 
 ## Overview
 
-Nuxt Content Assets enables locally-located assets in your [Nuxt Content](https://content.nuxtjs.org/) folder:
+Nuxt Content Assets enables locally-located assets in [Nuxt Content](https://content.nuxtjs.org/):
 
 ```
 +- content
@@ -43,7 +43,7 @@ Almost as much as being in the sea!
 <video src="media/seaside.mp4"></video>
 ```
 
-That's it!
+The module supports a variety of [common tags](#how-it-works) and has additional goodies such as [image sizing](#image-sizing) and [live-reload](#live-reload).  
 
 ## Demo
 
@@ -82,6 +82,8 @@ export default defineNuxtConfig({
 
 Run the dev server or build and local assets should now be served alongside markdown content.
 
+See the [How it works](#how-it-works) section for more information.
+
 ## Usage
 
 ### Overview
@@ -93,27 +95,7 @@ Use relative paths anywhere within your documents:
 <video src="media/video.mp4" />
 ```
 
-Relative paths are defined by anything not starting with a slash or `http`, for example:
-
-```
-image.jpg
-assets/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:
+Relative paths can be defined in frontmatter, as long as they are the only value:
 
 ```mdx
 ---
@@ -125,30 +107,22 @@ images:
 ---
 ```
 
-Then pass these to components like so:
+These values can then be passed to components:
 
 ```markdown
 ::gallery{:data="images"}
 ::
 ```
 
-> Note: to pass size hints in frontmatter, set the `imageSize` configuration [option](#image-size) to `'url'`
-
-See the [Demo](demo/content/recipes/index.md) for an example.
+See the [Demo](demo/content/recipes/index.md) for a component example.
 
-### Supported assets
+### Live reload
 
-The following file extensions are targeted by default:
+From version `0.9.0-alpha` assets are watched and live-reloaded!
 
-| 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`        |
+Any additions, moves or deletes, or modifications to image content will be updated in the browser automatically.
 
-See the [configuration](#output) section to modify or change this list, and the [Demo](demo/nuxt.config.ts) for an example.
-
-### Images
+### Image sizing
 
 The module can prevent content jumps by optionally writing image size information to generated `<img>` tags:
 
@@ -156,7 +130,7 @@ The module can prevent content jumps by optionally writing image size informatio
 <img src="/image.jpg?width=640&height=480" width="640" height="480" style="aspect-ratio:640/480">
 ```
 
-If you use [ProseImg](https://content.nuxtjs.org/api/components/prose) components, you can pass these values to your own markup:
+If you use [ProseImg](https://content.nuxtjs.org/api/components/prose) components, you can hook into these values via the `$attrs` property:
 
 ```vue
 <template>
@@ -172,36 +146,40 @@ export default {
 </script>
 ```
 
-See the [configuration](#image-size) section to add this, and the [Demo](demo/components/temp/ProseImg.vue) for an example.
+For more information see the [configuration](#image-size) section and [Demo](demo/components/temp/ProseImg.vue) for an example.
+
+## How it works
 
-### Build
+Nuxt Content Assets works by serving a _copy_ of your assets using [Nitro](https://nitro.unjs.io/guide/assets#custom-server-assets).
 
-Once the dev server or build is running, the following happens:
+When Nuxt builds, 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
+- all content sources are scanned for valid assets
+- found assets are copied to a temporary build folder
+- relative paths in markdown are rewritten to point at this folder
+- metadata such as image size is written to a lookup file
+- finally, Nitro serves the folder for public access
 
-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).
+Note only specific tags and attributes are targeted in the parsing phase for rewriting:
+
+```html
+<a href="...">
+<img src="...">
+<video src="...">
+<audio src="...">
+<source src="...">
+<embed src="...">
+<iframe src="...">
+```
 
 ## Configuration
 
-The module will run happily without configuration, but should you need to:
+You can configure the module like so:
 
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  'content-assets': {
-    // where to generate and serve the assets from
-    output: 'assets/content/[path]/[file]',
-    
-    // include additional extensions
-    additionalExtensions: 'html',
-    
-    // completely replace supported extensions
-    extensions: 'png jpg',
-    
+  'content-assets': {    
     // use aspect-ratio rather than attributes
     imageSize: 'style',
     
@@ -211,91 +189,27 @@ export default defineNuxtConfig({
 })
 ```
 
-### Output
-
-The output path can be customised using a template string:
-
-```
-assets/[name]-[hash].[ext]
-```
-
-The first part of the path is where you want content assets to be served from:
-
-```
-assets/
-```
-
-The optional second part of the path indicates the relative location of each asset.
-
-The table below shows replacements for the asset `content/posts/2023-01-01/featured.jpg`:
-
-| Token       | Description                                                                                        | Example                    |
-|-------------|----------------------------------------------------------------------------------------------------|----------------------------|
-| `[key]`     | The config key of the source (see [sources](https://content.nuxtjs.org/api/configuration#sources)) | `content`                  |
-| `[path]`    | The relative path of the source                                                                    | `content/posts/2023-01-01` |
-| `[folder]`  | The relative path of the file's folder                                                             | `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/[path]/[file]`       | `assets/content/posts/2023-01-01/featured.jpg` |
-| `assets/[folder]/[file]`     | `assets/posts/2023-01-01/featured.jpg`         |
-| `assets/[name]-[hash].[ext]` | `assets/featured-9M00N4l9A0.jpg`               |
-| `assets/[hash].[ext]`        | `assets/9M00N4l9A0.jpg`                        |
-
-Note that the module defaults to:
-
-```
-/assets/[path]/[file]
-```
-
-### 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 replace extensions, use `extensions`:
-
-```ts
-{
-  extensions: 'png jpg' // serve png and jpg files only
-}
-```
+Note that from version `0.9.0-alpha` the `output` location is no longer configurable; images are copied relative to their original locations. 
 
 ### Image size
 
-You can add image size hints to the generated images via attributes, style, or the URL.
-
-To add `style` aspect-ratio:
+You can add one or more image size hints to the generated images:
 
 ```ts
 {
-  imageSize: 'style'
+  imageSize: 'attrs url'
 }
 ```
 
-To add `width` and `height` attributes:
+Pick from the following switches:
 
-```ts
-{
-  imageSize: 'attrs'
-}
-```
+| Switch  | What it does                                                                 |
+|---------|------------------------------------------------------------------------------|
+| `style` | Adds `style="aspect-ratio:..."` to any `<img>` tag                           |
+| `attrs` | Adds `width` and `height` attributes to any `<img>` tag                      |
+| `url`   | Adds the `?width=...&height=...` query string to image frontmatter variables |
 
-If you add `attributes` only, include the following CSS in your app:
+Note: if you add `attrs` only, include the following CSS in your app:
 
 ```css
 img {
@@ -304,16 +218,6 @@ img {
 }
 ```
 
-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:

package/dist/module.d.ts

@@ -2,8 +2,6 @@ import * as _nuxt_schema from '@nuxt/schema';
 
 interface ModuleOptions {
     output?: string;
-    additionalExtensions?: string;
-    extensions?: string;
     imageSize?: string;
     debug?: boolean;
 }

package/dist/module.json

@@ -4,5 +4,5 @@
   "compatibility": {
     "nuxt": "^3.0.0"
   },
-  "version": "0.7.0"
+  "version": "0.9.0-alpha"
 }