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。