Skip to main content

静的アセット

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

デフォルトでは、これらのアセットをstaticフォルダ内に配置することを推奨します。 そのディレクトリに入れたファイルは、ディレクトリ階層を保ったまま、生成されたbuildフォルダのルートにコピーされます。 例： 静的フォルダにsun.jpgという名前のファイルを追加すると、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'],
  // ...
};

これで、static内だけでなくpublic内のファイルもすべてビルド出力にコピーされます。

静的アセットの参照​

JSX内​

JSXでは、絶対URLを使ってコード内のstaticフォルダからアセットを参照できますが、サイトのbaseUrlを変更するとそれらのリンクが壊れてしまうので、これは理想的ではありません。 https://example.com/testで配信されている画像<img src="/img/docusaurus.png" />に対して、ブラウザは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の静的アセットを参照してください。

次のようににリンクを書いたとします：[文書をダウンロード](/files/note.docx)

Docusaurusは、次のように変更します： <a href={require('static/files/note.docx')}>文書をダウンロード</a>
Markdown構文を使用すること

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

CSS内​

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

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

static/font/Caroline.otfアセットは、バンドラーによって読み込まれます。

重要なポイント

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

URLスラッグの概念モデルがより理解しやすいと思われる方は、次のような経験則を参考にしてください。

  • JSXを書くときは、/test/のようなベースURLがあることにして、src="/img/thumbnail.png"のような絶対URLパスを使わず、アセットをrequireします。
  • MarkdownやCSSを書くときは/であることにして、常にベースURLのない絶対パスを使います。

注意事項​

以下の点を頭に入れておいてください。

  • デフォルトでは、staticフォルダ内のファイルは、いずれも後処理、名前ハッシュ化、軽量化されません。
    • しかし、上記で示したように、通常それらをrequire呼び出しに変換できるので、それらは処理されることになります。 これは、積極的なキャッシュとより良好なユーザー体験のために有効です。
  • ハードコードされた絶対パスで参照されるファイルの欠落は、コンパイル時に検出されず、404エラーになります。
  • デフォルトでは、GitHub PagesはJekyllを介して公開ファイルを処理します。 Jekyllは_で始まるファイルを破棄するので、GitHubページをホスティングに使用している場合は、staticディレクトリに.nojekyllファイルという空のファイルを追加してJekyllを無効化することを推奨します。