Nuxt Content 資源

在 Nuxt Content 中啟用本地資源

Nuxt Content Assets logo

概述

Nuxt Content 資源可在 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">

請參閱此處的遊樂場元件。

Nuxt Image

透過將 Nuxt Content 資源的快取資料夾新增為 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'`	將 `style="aspect-ratio:..."` 新增至任何 `<img>` 標籤
`'attrs'`	將 `width` 和 `height` 屬性新增至任何 `<img>` 標籤
`'src'`	將 `?width=...&height=...` 新增至 `src` 屬性（僅限 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 Socket 通知瀏覽器重新整理任何載入的圖片。

如果使用 Nuxt Image，_ipx/ 端點會直接從快取的 public 資料夾提供圖片。

開發

如果您希望開發專案，您將使用以下實體

src
模組程式碼本身
遊樂場
一個獨立的 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

發佈

!重要在發佈之前，請務必更新版本和變更記錄！

若要建置和發佈，請根據需要執行下列腳本

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