Nuxt Content Assets

在 Nuxt Content 中启用本地资源

Nuxt Content Assets logo

概述

Nuxt Content Assets 允许在 Nuxt Content 中使用本地资源

+- content
    +- posts
        +- 2023-01-01
            +- index.md
            +- media
                +- featured.png
                +- mountains.jpg
                +- seaside.mp4

在您的文档中，使用相对路径引用资源

---
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"}

在构建时，模块将整理和提供资源和内容。

特性

构建于 Nuxt Content 之上，并与任何 Nuxt Content 项目或主题兼容，包括 Docus。

用户体验

将资源与内容文件放在一起
使用相对路径引用资源
支持任何格式（图片、视频、文档）

开发者体验

适用于标签和自定义组件
适用于 markdown 和 frontmatter
文件监视和资源实时重新加载
图片尺寸注入
零配置

Playground

为了在安装之前测试模块，您可以试用 Nuxt Content Assets playground。

本地克隆并运行

git clone https://github.com/davestewart/nuxt-content-assets.git
cd nuxt-content-assets
npm install && npm install --prefix ./playground
npm run dev

然后在浏览器中打开 playground，地址为 localhost:3000。

要在线运行 playground，请访问

https://stackblitz.com/github/davestewart/nuxt-content-assets?file=playground%2Fapp.vue

要浏览 playground 文件夹

https://github.com/davestewart/nuxt-content-assets/tree/main/playground

设置

安装依赖

npm install nuxt-content-assets

配置 nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-content-assets', // make sure to add before content!
    '@nuxt/content',
  ]
})

运行开发服务器或构建，本地资源现在应该与 markdown 内容一起提供。

用法

概述

在文档中的任何位置使用相对路径

Images
![image](image.jpg)

Links
[link](docs/article.txt)

Elements / components
:video{src="media/video.mp4"}

HTML
<iframe src="media/example.html" />

相对路径可以在 frontmatter 中定义 – 只要它们是唯一的值

---
title: Portfolio
images:
  - assets/image-1.jpg
  - assets/image-2.jpg
  - assets/image-3.jpg
---

这些值随后可以传递给组件

:image-gallery{:data="images"}

请参阅 playground 获取 markup 和 component 示例。

实时重新加载

在开发中，模块会监视资源的添加、移动和删除，并实时更新浏览器。

如果您删除一个资源，它将在浏览器中灰显，直到您替换该文件或修改其路径。

如果您编辑图片、视频、嵌入或 iframe 来源，内容将立即更新，如果您希望获得完美的设计，这将非常有用！

!NOTE 实时重新加载目前不适用于 Nuxt Image（请参阅 Issue #77）。
如果您需要迭代图片设计，请考虑在开发中禁用 Nuxt Image。

图片尺寸调整

HTML

模块可以将图片尺寸提示传递给生成的 <img> 标签

<!-- imageSize: 'style' -->
<img src="/image.jpg" style="aspect-ratio:640/480">

<!-- imageSize: 'attrs' -->
<img src="/image.jpg" width="640" height="480">

启用此功能可防止页面加载时内容跳动。

!CAUTION 请勿将 imageSize: 'src' 与 Nuxt Image 结合使用，因为它会阻止 IPX 模块正确地提供图片，从而导致静态站点生成失败

Prose 组件

如果您使用 ProseImg 组件，您可以通过 hook into $attrs 属性挂钩到图片尺寸提示

<template>
  <span class="image">
    <img :src="$attrs.src" :width="$attrs.width" :height="$attrs.height" />
  </span>
</template>

<script>
export default {
  inheritAttrs: false
}
</script>

Frontmatter

如果您将 frontmatter 传递给自定义组件，请将 imageSize 设置为 'src' 以在 src 中编码值

:image-content{:src="image"}

组件将收到作为查询字符串的大小信息，您可以提取并应用它

<img class="image-content" src="/image.jpg?width=640&height=480">

请此处查看 playground 组件。

Nuxt Image

通过将 Nuxt Content Asset 的缓存文件夹添加为 Nuxt Layer，可以支持 Nuxt Image

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    'node_modules/nuxt-content-assets/cache',
  ],
}

要将所有图片作为 Nuxt Image 图片提供，请创建一个如下所示的 ProseImg 组件

<!-- components/content/ProseImg.vue -->
<template>
  <nuxt-img />
</template>

请参阅 playground 文件夹以获取全局和全局和每个图片解决方案。

配置

该模块具有以下选项

// nuxt.config.ts
export default defineNuxtConfig({
  contentAssets: {    
    // inject image size hints into the rendered html
    imageSize: 'style',
    
    // treat these extensions as content
    contentExtensions: 'mdx? csv ya?ml json',
    
    // output debug messages
    debug: false,
  }
})

图片尺寸

!注意
自 v1.4.1 起，图片尺寸提示现在是可选加入的。这样做是为了最大限度地提高与 Nuxt Image 的兼容性。

您可以向生成的图片添加一个或多个图片尺寸提示

{
  imageSize: 'style attrs src'
}

从以下开关中选择

开关	作用
`'style'`	向任何 `<img>` 标签添加 `style="aspect-ratio:..."`
`'attrs'`	向任何 `<img>` 标签添加 `width` 和 `height` 属性
`'src'`	向 `src` 属性添加 `?width=...&height=...` (仅限 frontmatter)

注意：如果您仅添加 attrs，请在您的应用程序中包含以下 CSS

img {
  max-width: 100%;
  height: auto;
}

内容扩展

!NOTE 通常，您不需要修改此设置

此设置告诉 Nuxt Content 忽略任何不是受支持内容类型之一的内容

mdx? csv ya?ml json

这样，您可以使用任何其他文件类型作为资源，而无需显式配置 Nuxt Content 的 ignores 列表。

没有此设置，Nuxt Content 会警告有关不受支持的文件类型

WARN 不支持 .jpg 文件，“content:path:to:some-asset.jpg” 回退到原始内容

调试

如果您想查看模块在运行时执行的操作，请将 debug 设置为 true

{
  debug: true
}

工作原理

当 Nuxt 构建时，模块会扫描所有内容源以查找资源，将它们复制到临时图层文件夹 (nuxt_modules/nuxt-content-assets/cache)，并索引路径和图片元数据。

在 Nuxt Content 运行后，将遍历解析后的内容 (.nuxt/content-cache)，并检查元素属性和 frontmatter 属性，以查看它们是否解析为先前索引的资源路径。

如果它们确实解析为资源路径，则 Nuxt Content 缓存中的属性或属性将使用绝对路径重写。如果资源是图片，则元素或元数据可以选择性地使用尺寸属性或查询字符串进行更新。

最后，Nitro 提供站点服务，并且对转换后的资源路径的任何请求都应被拾取，并且复制的资源由浏览器提供服务。

在开发中，监视进程将资源更改传播到缓存，更新资源索引，并通过 web sockets 通知浏览器刷新任何已加载的图片。

如果使用 Nuxt Image，则 _ipx/ 端点直接从缓存的 public 文件夹提供图片。

开发

如果您希望开发该项目，您将使用以下实体

src
模块代码本身
playground
一个独立的 Nuxt 应用程序，用于读取实时模块代码
scripts
一组用于开发和发布模块的脚本

设置

要设置项目，请运行每个脚本一次

# install dependencies
npm install

# copy the cache folder to the playground's node_modules (workaround required in development)
npm run dev:setup

# generate types for the module and playground (re-run if you install new packages)
npm run dev:prepare

开发

要开发模块，请使用提供的 playground 应用程序

# compile the module, run and serve the playground
npm run dev

# generate the playground
npm run dev:generate

# build the playground
npm run dev:build

# serve the generated/built playground
npm run dev:preview

使用这些工具检查您的代码质量

# lint your code with eslint
npm run lint

# runs tests with vitest
npm run test
npm run test:watch

发布

!IMPORTANT 在发布之前，请务必更新 version 和 changelog！

要构建和发布，请根据需要运行以下脚本

# lint, test, build, and dry-run publish
npm run release:dry

# lint, test, build and publish
npm run release

维护

此模块是使用 Nuxt Module Builder 命令创建的

npx nuxi init -t module nuxt-content-assets

这从此处找到的入门模板创建了模块代码

https://github.com/nuxt/starter/tree/module

Nuxi 和模块的依赖项和脚本都会定期更新，因此有时可能需要更新此模块以保持同步。到目前为止，这意味着只需更新依赖项和脚本，这些依赖项和脚本可以在上面提到的入门模板代码中找到。

请注意，build/release 脚本与原始脚本略有不同；build 现在已分离，release 现在不使用 changelogen，也不自动添加标签和推送到 GitHub。