アセットビューアー

作成 2026年8月30日更新 2026年9月1日Takeshi Takatsudo

ドキュメント外のファイルに、内容を確認できる専用ページと参照経路を与える。

アセットビューアーが役立つ場面

ヘルパースクリプト、構成図、操作動画、PDF 仕様書、配布用アーカイブなど、ドキュメントの本文には埋め込まず、別ファイルのまま説明したい資料があります。アセットビューアーを使うと、ファイルを public/ に置いたまま専用の閲覧ページを生成し、MDX 内の参照をそのページにつなげられます。

単にファイルを返すだけでは読者に十分な手掛かりを示せない場合に、この機能を有効にします。

zfb.config.ts

import { defineConfig } from "zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";

export default defineConfig(
  zudoDoc({
    assetViewer: true,
    imageEnlarge: true,
  }),
);

imageEnlarge: true は、ドキュメントに埋め込んだ画像をクリックして拡大する機能を有効にします。画像キャプションからアセットページへ移動するリンクは、拡大表示を無効にしても利用できます。

ディレクトリと URL の構成

ビューアーで扱うファイルは public/<assetViewerDir>/ 配下に置きます。デフォルト設定では、次の構成になります。

public/
└── assets/
    └── demo/
        ├── architecture.png
        ├── demo-project.zip
        ├── diagrams/
        │   ├── link-graph.svg
        │   └── link-graph.svg.meta.json
        ├── hmr-demo.mp4
        ├── parse-frontmatter.js
        ├── scripts/
        │   ├── README.txt
        │   └── check-frontmatter.mjs
        └── spec.pdf

各ファイルに対して、用途の異なる2つの URL ができます。

/assets/demo/parse-frontmatter.js は公開ファイルそのものを返す URL です。画像、メディアプレーヤー、ダウンロード操作はこの URL を使います。
/files/demo/parse-frontmatter.js/ は生成された閲覧ページです。ファイル情報、プレビュー操作、ダウンロード操作、このファイルを参照しているドキュメントへのリンクが加わります。

サイトにルート以外の base を設定している場合も、ルート相対 URL のまま記述できます。レンダリング時に zudo-doc が設定済みの base を付与します。

設定

zudoDoc() のトップレベルで、次の6項目を設定できます。

フィールド	デフォルト	用途
`assetViewer`	`false`	閲覧ページを生成し、マニフェストに基づく MDX の参照機能を有効にする。
`assetViewerDir`	`"assets"`	`public/` 配下のディレクトリと、公開ファイルの URL プレフィックスを指定する。
`assetViewerRoutePrefix`	`"files"`	閲覧ページの URL プレフィックスを指定する。`assetViewerDir` とは異なる値が必要。
`assetViewerExclude`	`[]`	アセットディレクトリからの相対パスに対して、閲覧ページの生成対象外にする glob を指定する。
`assetViewerIndex`	`false`	ビューアーのルートプレフィックスに一覧ページを生成する。
`assetViewerIndexing`	`false`	閲覧ページを検索、`llms.txt`、サイトマップの各出力へ個別に追加する。

たとえば、ソースマップと下書きを通常の公開ファイルとして残しつつ、閲覧ページだけを生成対象外にするには次のように設定します。

zfb.config.ts

export default defineConfig(
  zudoDoc({
    assetViewer: true,
    assetViewerExclude: ["**/*.map", "drafts/**"],
  }),
);

ビューアーで管理するファイルを public/<assetViewerDir>/client/ 配下には置かないでください。client/ は zfb がブラウザー向けアセット用に予約しているパスであり、アセットビューアーは走査時に衝突を報告します。

アセット一覧ページ

アセットビューアーと一覧を有効にすると、/<assetViewerRoutePrefix>/ にファイルを見渡せるページが生成されます。

zfb.config.ts

export default defineConfig(
  zudoDoc({
    assetViewer: true,
    assetViewerIndex: true,
  }),
);

一覧には、対象アセットがディレクトリツリーとして表示されます。フォルダー行はリンクではなく、配下を開閉するためのトグルです。フォルダーごとに配下のファイル数と合計サイズが表示されます。ファイル行からは各閲覧ページへ移動でき、ファイル種別やサイズなどの情報も確認できます。対象ファイルが1つもない場合は、ツリーの代わりに空の状態を示すメッセージが表示されます。

assetViewerExcludeで除外したファイルは閲覧ページと一覧のどちらにも現れませんが、元の公開URLからは引き続き取得できます。メタデータサイドカーも一覧には含まれません。一覧ページは個別の閲覧ページと同様、設定済みの各ロケールに生成されます。

このショーケースでは機能を有効にしているため、実際のアセット一覧を確認できます。自分のサイトのヘッダーから一覧へ移動できるようにするには、headerNav にバージョン非依存の項目を追加します。

zfb.config.ts

export default defineConfig(
  zudoDoc({
    assetViewer: true,
    assetViewerIndex: true,
    headerNav: [
      { label: "Assets", labelKey: "nav.assets", path: "/files", versioned: false },
    ],
  }),
);

versioned: falseを指定すると、リンクがアーカイブ版のルートに入りません。ロケール対応ナビゲーションは、現在のロケールプレフィックスを自動的に追加します。項目の設定全般はヘッダーナビゲーションを参照してください。

アセットページをインデックスへ追加する

デフォルトでは、アセット閲覧ページは検索インデックス、llms.txt、サイトマップのいずれにも含まれません。assetViewerIndexing を使うと、出力先ごとに追加を有効化できます。

zfb.config.ts

export default defineConfig(
  zudoDoc({
    assetViewer: true,
    assetViewerIndexing: {
      search: true,
      llmsTxt: true,
      sitemap: true,
    },
  }),
);

設定値の型は false | { search?: boolean; llmsTxt?: boolean; sitemap?: boolean } で、デフォルトは false です。各キーは明示的に true を指定した場合にだけ有効になるため、一部のキーだけを持つオブジェクトでは、省略した出力先は無効のままです。また、assetViewer: true が前提となり、インデックス用のキーだけを有効にしても何も起こりません。

各キーが制御する出力は次のとおりです。

search は、アセット閲覧ページを search-index.json に追加します。各ページの ID には asset: プレフィックスが付きます。
llmsTxt は、llms.txt に ## Files セクションを追加し、llms-full.txt にアセットページを追記します。テキストとして扱えるアセットでは本文を最大 8 KB まで収録し、それを超える場合は末尾に切り詰めを明示するマーカーを付けます。バイナリアセットは本文を含めず、1 行のスタブとして掲載します。
sitemap は、/files/... の閲覧ページルートをサイトマップに追加します。

このショーケースでは 3 つのキーをすべて有効にしているため、生成される検索インデックス、LLM 向けファイル、サイトマップで、すべての出力を有効にした場合の挙動を確認できます。

MDX から参照する方法

以下はすべて、このリポジトリのデモファイルを参照する実際の表示例です。

Markdown リンク

マニフェストに存在する公開ファイルへの Markdown リンクは閲覧ページの URL に書き換えられ、ファイル種別とサイズが付加されます。

parse-frontmatter.js(2.9 KB) を生成された閲覧ページで開きます。

[parse-frontmatter.js](/assets/demo/parse-frontmatter.js)

外部リンク、ページ内リンク、除外対象のパス、マニフェストにない公開 URL は通常のリンクのままです。

アセットカード

そのファイル自体が主要な配布物や参照資料である場合は Asset を使います。カードから、説明付きの閲覧ページと元ファイルのダウンロードの両方へ移動できます。

demo/demo-project.zip

File · 2.1 KB

ファイル全体を見る →ダウンロード →

<Asset src="/assets/demo/demo-project.zip" />

ドキュメント固有の表現が必要な場合は、Asset に任意の title と description props も指定できます。

コードの抜粋

ソースファイルの一部を MDX へ複製せずに掲載するには AssetCode を使います。

demo/parse-frontmatter.jslines 27–44

export function parseFrontmatter(source, options = {}) {
  const { strict = false } = options;

  if (!FENCE_RE.test(source)) {
    return { data: {}, body: source, hasFrontmatter: false };
  }

  const end = source.indexOf(`\n${FENCE}`, FENCE.length);
  if (end === -1) {
    if (strict) throw new Error('Unterminated frontmatter block');
    return { data: {}, body: source, hasFrontmatter: false };
  }

  const yaml = source.slice(FENCE.length, end).replace(/^\r?\n/, '');
  const body = source.slice(end + FENCE.length + 1).replace(/^\r?\n/, '');

  return { data: parseYamlSubset(yaml), body, hasFrontmatter: true };
}

<AssetCode src="/assets/demo/parse-frontmatter.js" lines="27-44" />

指定した行はビルド時に抽出され、シンタックスハイライト付きで表示されます。フッターのリンクから、閲覧ページ上の同じ範囲へ移動できます。1つの抜粋で指定できるのは最大200行です。

画像キャプションのリンク

単独の画像がアセットマニフェストに含まれている場合、ドキュメント内での通常表示を保ったまま、キャプションに Open asset page リンクが加わります。

Asset pipeline diagram⤢ Open asset page · 3200 × 1800

![Asset pipeline diagram](/assets/demo/architecture.png "Figure 1 — the asset viewer pipeline.")

リンクには画像の寸法も表示されます。imageEnlarge: true の場合は、同じ画像を拡大ダイアログでも確認できます。操作方法と記述規則は Image Enlargeを参照してください。

任意のメタデータサイドカー

閲覧ページのタイトルを変えたり説明を追加したりするには、アセットと同じ場所に <file>.meta.json を置きます。デモファイルには、diagrams/link-graph.svg と同じ場所に link-graph.svg.meta.json が用意されています。

public/assets/demo/diagrams/link-graph.svg.meta.json

{
  "title": "Asset link graph",
  "description": "How a document link maps to the raw asset URL and its generated viewer page."
}

どちらも任意の文字列フィールドです。サイドカーは正しい JSON 形式で、2 KB 以下にしてください。ビルド時のメタデータとしてだけ使われるため、.meta.json 自体の閲覧ページは生成されません。

ファイル種別ごとの表示

どの閲覧ページにも、ファイル名とメタデータ、元ファイルに対する操作、詳細情報、このファイルを参照しているドキュメントへのリンクが表示されます。中央のプレビューは、検出されたファイル種別に応じて変わります。

コードとテキスト(2.9 KB): 行アンカー付きのソース、コピー操作、折り返し操作を表示します。1 MiB 以下のファイルはシンタックスハイライトされ、それを超えるテキストはプレーン表示になります。プレーン表示は最大2,000行で、5 MiB を超えるテキストはダウンロード専用になります。
画像(126 KB): Fit と 1:1 の表示倍率、チェッカー背景と暗色背景、画像寸法、拡大ダイアログを利用できます。
動画(203 KB): ブラウザー標準の操作 UI を使い、取得できた場合は寸法と再生時間も表示します。
PDF(1.5 KB): ブラウザーの PDF ビューアーを埋め込み、その横にダウンロード手段も残します。
アーカイブなど未対応の形式(2.1 KB): 安全性や正確性に欠けるプレビューは試みず、ダウンロードパネルを表示します。

形式の判定では拡張子だけでなくファイル内容も確認します。両者が一致しない場合は、申告されたメディア形式として埋め込まず、安全な表示へ切り替えます。

開発時の挙動

pnpm dev の実行中に既存アセットを編集すると、閲覧ページにも変更が反映されます。一方、監視対象はプラグイン起動時に列挙されるため、アセットを追加、削除、または名前変更した場合は pnpm dev の再起動が必要です。再起動するまで、アセット一覧にも古い内容が残ります。ドキュメントから初めてアセットを参照した場合も、リンク関係と抜粋を再構築するために再起動してください。

ファイルの追加や整理を繰り返す間は、ビルドしてから配信する開発モードの pnpm dev:stable を使うこともできます。

生成ルートの挙動

個別のアセット閲覧ページはリーフページであり、任意で有効にできるルートプレフィックス直下のページはアセット一覧です。どちらも設定済みの各ロケールに存在し、生成されたドキュメントリンクと一覧リンクはそのロケールを保持します。たとえば、日本語ページからは/files/.../ではなく/ja/files/.../が開きます。これらのルートは、ドキュメントのサイドバーには掲載されません。検索インデックス、llms.txt、サイトマップにもデフォルトでは含まれず、対応する assetViewerIndexing のキーを明示的に有効化した場合にだけ追加されます。

ビューアーのクロームはasset.*翻訳名前空間で解決され、詳細、種類、全体表示、チェッカーなどのラベルも含まれます。パッケージが同梱するのは英語と日本語の文字列で、他のロケールは通常の翻訳フォールバックに従います。各文字列はZudoDocConfig.translationsで上書きできます。以前のデフォルトロケール限定の挙動に戻すには、/${assetViewerRoutePrefix}/をdefaultLocaleOnlyPrefixesに追加してください。詳しくは国際化を参照してください。

閲覧ページはサイトの noindex 設定に従います。ヘッダーとフッターなどのドキュメント共通 UI は保ちつつ、ドキュメント用のサイドバーと目次は表示しません。

GitHub でソースを見る

アセットビューアー