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上に構築され、Docusを含むあらゆるNuxt Contentプロジェクトまたはテーマと互換性があります。

ユーザー体験

コンテンツファイルとアセットを併置する
相対パスを使用してアセットを参照する
あらゆるフォーマット（画像、動画、ドキュメント）をサポート

開発者体験

タグとカスタムコンポーネントで動作
マークダウンとフロントマターで動作
ファイル監視とアセットのライブリロード
画像サイズ注入
ゼロコンフィグ

プレイグラウンド

インストール前にモジュールをテストするには、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',
  ]
})

開発サーバーを実行するか、ビルドすると、ローカルアセットがマークダウンコンテンツと並行して提供されるようになります。

使用方法

概要

ドキュメント内のどこでも相対パスを使用する

Images
![image](image.jpg)

Links
[link](docs/article.txt)

Elements / components
:video{src="media/video.mp4"}

HTML
<iframe src="media/example.html" />

相対パスはフロントマターで定義できます – ただし、それが唯一の値である場合に限ります

---
title: Portfolio
images:
  - assets/image-1.jpg
  - assets/image-2.jpg
  - assets/image-3.jpg
---

これらの値はコンポーネントに渡すことができます

:image-gallery{:data="images"}

マークアップとコンポーネントの例はプレイグラウンドをご覧ください。

ライブリロード

開発モードでは、モジュールはアセットの追加、移動、削除を監視し、ブラウザをライブで更新します。

アセットを削除すると、そのファイルが置き換えられるかパスが変更されるまで、ブラウザではグレー表示されます。

画像、動画、埋め込み、または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モジュールが画像を正しく提供するのを妨げ、静的サイト生成が失敗する原因となります。

プロズコンポーネント

ProseImgコンポーネントを使用する場合、$attrsプロパティを介して画像サイズのヒントをフックできます。

<template>
  <span class="image">
    <img :src="$attrs.src" :width="$attrs.width" :height="$attrs.height" />
  </span>
</template>

<script>
export default {
  inheritAttrs: false
}
</script>

フロントマター

フロントマターをカスタムコンポーネントに渡す場合、imageSizeを'src'に設定して、srcに値をエンコードします。

:image-content{:src="image"}

コンポーネントは、抽出して適用できるクエリ文字列としてサイズ情報を受け取ります。

<img class="image-content" src="/image.jpg?width=640&height=480">

プレイグラウンドコンポーネントの例はこちらをご覧ください。

Nuxt Image

Nuxt Imageは、Nuxt Content AssetのキャッシュフォルダをNuxtレイヤーとして追加することでサポートされます。

// 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との互換性を最大化するために行われました。

生成された画像に1つまたは複数の画像サイズヒントを追加できます。

{
  imageSize: 'style attrs src'
}

以下のスイッチから選択してください

スイッチ	機能
`'style'`	すべての`<img>`タグに`style="aspect-ratio:..."`を追加
`'attrs'`	任意の`<img>`タグに`width`および`height`属性を追加します。
`'src'`	`src`属性に`?width=...&height=...`を追加（フロントマターのみ）

注: 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」はrawコンテンツにフォールバックします。

デバッグ

モジュールの実行中の動作を確認したい場合は、debugをtrueに設定してください。

{
  debug: true
}

仕組み

Nuxtがビルドされる際、モジュールはすべてコンテンツソースをスキャンしてアセットを探し、それらを一時的なレイヤーフォルダ（nuxt_modules/nuxt-content-assets/cache）にコピーし、パスと画像メタデータをインデックス化します。

Nuxt Contentの実行後、解析されたコンテンツ（.nuxt/content-cache）が走査され、要素属性とフロントマタープロパティの両方が、以前にインデックス化されたアセットパスに解決されるかどうかを確認されます。

もしそうであれば、Nuxt Contentのキャッシュ内の属性またはプロパティは絶対パスで書き換えられます。アセットが画像の場合、要素またはメタデータはオプションでサイズ属性またはクエリ文字列で更新されます。

最後に、Nitroがサイトを提供し、変換されたアセットパスへのリクエストはすべて検出され、*コピーされた*アセットがブラウザによって提供されるはずです。

開発では、監視プロセスがアセットの変更をキャッシュに伝播し、アセットインデックスを更新し、ウェブソケットを介してブラウザにロードされた画像を更新するように通知します。

Nuxt Imageが使用されている場合、_ipx/エンドポイントはキャッシュのpublicフォルダから直接画像を配信します。

開発

プロジェクトを開発したい場合は、以下のエンティティを扱います。

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

公開

!IMPORTANT 公開する前に、必ずバージョンと変更履歴を更新してください！

ビルドと公開には、必要に応じて以下のスクリプトを実行してください。

# 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

これは、ここにあるスターターテンプレートからモジュールコードを作成しました。

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

Nuxiとモジュールの依存関係とスクリプトはかなり定期的に更新されるため、このモジュールも同期を保つために時々更新する必要があるかもしれません。これまでのところ、これは上記のスターターテンプレートコードにある依存関係とスクリプトを更新するだけで済みました。

ビルド/リリーススクリプトはオリジナルからわずかに修正されていることに注意してください。ビルドは分離され、リリースはchangelogenを使用せず、タグの自動追加やGitHubへのプッシュも行いません。