本文へ移動
バージョン: 3.5.2

静的アセット

静的アセットとは、ビルド出力に直接コピーされるコード以外のファイルです。画像、スタイルシート、ファビコン、フォントなどが含まれます。

デフォルトでは、これらのアセットを`static`フォルダに配置することをお勧めします。**このディレクトリに配置したすべてのファイルは、ディレクトリ階層を維持した状態で、生成された`build`フォルダのルートにコピーされます。** 例えば、`sun.jpg`というファイルをstaticフォルダに追加すると、`build/sun.jpg`にコピーされます。

つまり、

  • サイトの`baseUrl: '/'`の場合、画像`/static/img/docusaurus.png`は`/img/docusaurus.png`で提供されます。
  • サイトの`baseUrl: '/subpath/'`の場合、画像`/static/img/docusaurus.png`は`/subpath/img/docusaurus.png`で提供されます。

`docusaurus.config.js`で静的ディレクトリのソースをカスタマイズできます。例えば、`public`を別のパスとして追加できます。

docusaurus.config.js
export default {
  title: 'My site',
  staticDirectories: ['public', 'static'],
  // ...
};

これで、`public`と`static`の両方のファイルがビルド出力にコピーされます。

静的アセットの参照​

JSX で​

JSX では、絶対URLを使用してコード内で`static`フォルダからアセットを参照できますが、これは理想的ではありません。サイトの`baseUrl`を変更すると、**これらのリンクが壊れる**可能性があります。`https://example.com/test`で提供される画像``の場合、ブラウザはURLルート、つまり`https://example.com/img/docusaurus.png`から解決しようとしますが、実際には`https://example.com/test/img/docusaurus.png`で提供されるため失敗します。

静的アセットを`import()`または`require()`することができます（推奨）。または、`useBaseUrl`ユーティリティ関数を使用することもできます。どちらも、パスに`baseUrl`を事前に追加します。

例

MyComponent.js
import DocusaurusImageUrl from '@site/static/img/docusaurus.png';

<img src={DocusaurusImageUrl} />;
MyComponent.js
<img src={require('@site/static/img/docusaurus.png').default} />
MyComponent.js
import useBaseUrl from '@docusaurus/useBaseUrl';

<img src={useBaseUrl('/img/docusaurus.png')} />;

SVGファイルもインポートできます。Reactコンポーネントに変換されます。

MyComponent.js
import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';

<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;

Markdown で​

Markdownでは、**Markdown構文で**リンクや画像を作成する際に絶対パスを使用できます。Docusaurusは、Markdownの解析時にURLではなく`require`呼び出しとして処理します。Markdown静的アセットを参照してください。

You write a link like this: [Download this document](/files/note.docx)

Docusaurus changes that to: <a href={require('static/files/note.docx')}>Download this document</a>
Markdown構文を使用する

Docusaurusは、Markdown構文のリンクのみを解析します。アセット参照がJSXタグ`` / ``を使用している場合、何も行われません。

CSS で​

CSSでは、`url()`関数は一般的にフォントや画像などのアセットを参照するために使用されます。静的アセットを参照するには、絶対パスを使用します。

@font-face {
  font-family: 'Caroline';
  src: url('/font/Caroline.otf');
}

`static/font/Caroline.otf`アセットはバンドラによってロードされます。

重要なポイント

重要なポイントの1つ：**ベースURLを決してハードコーディングしないでください！** ベースURLは実装の詳細とみなされ、簡単に変更できる必要があります。パスは、URLスラッグのように見える場合でも、実際にはファイルパスです。

URLスラッグのメンタルモデルの方が分かりやすい場合は、次の経験則があります。

  • JSX を記述する際は、`baseUrl` が `/test/` のようなものであると想定して、`src="/img/thumbnail.png"` のような絶対URLパスを使用するのではなく、アセットを `require` します。
  • Markdown または CSS を記述する際は、`baseUrl` が `/` であると想定して、常にベースURLを含まない絶対パスを使用します。

注意点​

考慮すべき点

  • デフォルトでは、`static`フォルダ内のファイルは、ポストプロセス、ハッシュ化、またはミニファイ化されません。
    • しかし、上記で説明したように、通常は`require`呼び出しに変換できるため、処理されます。これは、積極的なキャッシングとより良いユーザーエクスペリエンスに役立ちます。
  • ハードコードされた絶対パスを介して参照される欠落ファイルは、コンパイル時に検出されず、404エラーになります。
  • デフォルトでは、GitHub Pages は公開されたファイルを Jekyll を使用して実行します。Jekyll は `_` で始まるファイルを破棄するため、GitHub Pages をホスティングに使用している場合は、`static` ディレクトリに ` .nojekyll` という名前の空のファイルを追加して Jekyll を無効にすることをお勧めします。