nuxt-content-assets

在 Nuxt Content 中启用本地资产

1.8K 次下载•119 颗星•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 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。

实时重载

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

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

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

!注意实时重载目前不适用于 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">

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

!注意不要将 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">

请参阅此处playground 组件。

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>

有关全局和每个图像解决方案，请参阅 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;
}

内容扩展

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

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

mdx? csv ya?ml json

通过这种方式，您可以将任何**其他**文件类型用作资产，而无需明确配置 Nuxt Content 的忽略列表。

否则，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 提供站点，对转换后的资产路径的任何请求都应该被浏览器接收并提供**复制的**资产。

在开发中，一个监视进程会将资产更改传播到缓存，更新资产索引，并通过 WebSocket 通知浏览器刷新任何已加载的图像。

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

开发

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

src
模块代码本身
playground
一个读取实时模块代码的独立 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

开发

要开发模块，请使用提供的 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

发布

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

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

# 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。