nuxt-content-assets

在 Nuxt Content 中启用本地资产

2.5K 次下载•120 星•v1.4.4

davestewart

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
文件监视和资产实时重载
图片尺寸注入
零配置

演示

在安装模块之前，您可以尝试 Nuxt Content Assets 演练场。

克隆并在本地运行

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

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

要在在线运行演练场，请访问

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

要浏览演练场文件夹

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

请参阅演练场中的标记和组件示例。

实时重载

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

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

如果您编辑图片、视频、嵌入或 iframe 源，内容将立即更新，这对于您想要完美设计非常有用！

!注意实时重载目前不适用于 Nuxt Image（请参阅问题 #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">

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

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

Prose 组件

如果您使用 ProseImg 组件，您可以通过 $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">

请参阅此处的演练场组件。

Vercel 上使用 Nuxt Image

通过将 Nuxt Content Asset 的缓存文件夹添加为 Nuxt 层来支持 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>

请参阅演练场文件夹，了解全局和每张图片的解决方案。

配置

该模块具有以下选项

// 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;
}

内容扩展

!注意通常，您不需要更改此设置

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

mdx? csv ya?ml json

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

如果没有此设置，Nuxt Content 将会警告不支持的文件类型

警告不支持 .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/ 端点直接从缓存的公共文件夹提供图片。

开发

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

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

设置

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

# 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

开发

要开发模块，请使用提供的演练场应用程序

# 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

发布

!重要在发布之前，请务必更新版本和更新日志！

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

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

# lint, test, build and publish
npm run release

维护

此模块是使用 Nuxt 模块构建器命令创建的

npx nuxi init -t module nuxt-content-assets

这从此处找到的启动模板创建了模块代码

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

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

请注意，构建/发布脚本与原始脚本略有修改；构建现在已分离，发布现在不使用 changelogen，也不自动添加标签并推送到 GitHub。