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

請參閱體驗場以取得 markup 和組件範例。

即時重新載入

在開發中，此模組會監看資源的添加、移動和刪除，並即時更新瀏覽器。

如果您刪除資源，它將在瀏覽器中呈現灰色，直到您替換該檔案或修改其路徑。

如果您編輯圖片、影片、嵌入或 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 組件，您可以透過 $attrs 屬性 hook into 圖片尺寸提示

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

請參閱此處的體驗場組件 here。

Nuxt Image

Nuxt Image 透過將 Nuxt Content Asset 的快取資料夾新增為 Nuxt Layer 來支援

// 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'`	將 `style="aspect-ratio:..."` 新增到任何 `<img>` 標籤
`'attrs'`	將 `width` 和 `height` 屬性新增到任何 `<img>` 標籤
`'src'`	將 `?width=...&height=...` 新增到 `src` 屬性（僅限 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

開發

若要開發模組，請使用提供的體驗場應用程式

# 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 在發布之前，請務必更新版本和 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

這從此處找到的 starter 模板建立模組程式碼

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

Nuxi 和模組的依賴套件和腳本都會定期更新，因此此模組可能需要不時更新以保持同步。到目前為止，這僅表示更新依賴套件和腳本，這些都可以在上面提到的 starter 模板程式碼中找到。

請注意，建置/發布腳本與原始腳本略有不同；建置現在是分開的，並且發布現在不使用 changelogen，也不會自動新增標籤和推送到 GitHub。