アセット

Sometimes you want to link to assets (e.g. docx files, images...) directly from Markdown files, and it is convenient to co-locate the asset next to the Markdown file using it.

例えば、以下のファイル構成が与えられたとしましょう：

# あなたのドキュメント
/website/docs/myFeature.mdx

# あなたが利用したいアセット
/website/docs/assets/docusaurus-asset-example-banner.png
/website/docs/assets/docusaurus-asset-example.docx

画像

マークダウン構文、CJS要求、ESインポート構文の3つの方法で画像を表示できます。

Markdown syntax

Display images using simple Markdown syntax:

![参考バナー](./assets/docusaurus-asset-example-banner.png)

CommonJS require

Display images using inline CommonJS require in JSX image tag:

<img
  src={require('./assets/docusaurus-asset-example-banner.png').default}
  alt="参考バナー"
/>

Import statement

Display images using ES import syntax and JSX image tag:

import myImageUrl from './assets/docusaurus-asset-example-banner.png';

<img src={myImageUrl} alt="Example banner" />;

All of the above result in displaying the image:

http://localhost:3000

メモ

If you are using @docusaurus/plugin-ideal-image, you need to use the dedicated image component, as documented.

Files

In the same way, you can link to existing assets by require'ing them and using the returned URL in videos, a anchor links, etc.

# My Markdown page

<a target="\_blank" href={require('./assets/docusaurus-asset-example.docx').default}> Download this docx </a>

or

[Download this docx using Markdown](./assets/docusaurus-asset-example.docx)

http://localhost:3000

Download this docx

Download this docx using Markdown

Markdown links are always file paths

If you use the Markdown image or link syntax, all asset paths will be resolved as file paths by Docusaurus and automatically converted to require() calls. You don't need to use require() in Markdown unless you use the JSX syntax, which you do have to handle yourself.

Inline SVGs

Docusaurus supports inlining SVGs out of the box.

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;

http://localhost:3000

This can be useful if you want to alter the part of the SVG image via CSS. For example, you can change one of the SVG colors based on the current theme.

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg className="themedDocusaurus" />;

[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] {
  fill: greenyellow;
}

[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
  fill: seagreen;
}

http://localhost:3000

Themed Images

Docusaurus supports themed images: the ThemedImage component (included in the themes) allows you to switch the image source based on the current theme.

import useBaseUrl from '@docusaurus/useBaseUrl';
import ThemedImage from '@theme/ThemedImage';

<ThemedImage
  alt="Docusaurus themed image"
  sources={{
    light: useBaseUrl('/img/docusaurus_light.svg'),
    dark: useBaseUrl('/img/docusaurus_dark.svg'),
  }}
/>;

http://localhost:3000

GitHub-style themed images

GitHub uses its own image theming approach with path fragments, which you can easily implement yourself.

To toggle the visibility of an image using the path fragment (for GitHub, it's #gh-dark-mode-only and #gh-light-mode-only), add the following to your custom CSS (you can also use your own suffix if you don't want to be coupled to GitHub):

src/css/custom.css

[data-theme='light'] img[src$='#gh-dark-mode-only'],
[data-theme='dark'] img[src$='#gh-light-mode-only'] {
  display: none;
}

![Docusaurus themed image](/img/docusaurus_keytar.svg#gh-light-mode-only)![Docusaurus themed image](/img/docusaurus_speed.svg#gh-dark-mode-only)

http://localhost:3000

Static assets

If a Markdown link or image has an absolute path, the path will be seen as a file path and will be resolved from the static directories. For example, if you have configured static directories to be ['public', 'static'], then for the following image:

my-doc.md

![An image from the static](/img/docusaurus.png)

Docusaurus will try to look for it in both static/img/docusaurus.png and public/img/docusaurus.png. 次に、リンクはURLのままではなく require()呼び出しへと変換されます。 これは2つの観点から望ましいといえます：

1. ベースURLについて心配する必要はありません。アセットを配信する際はDocusaurusが適切に処理します。
2. 画像はWebpackのビルドパイプラインに取り込まれ、名前の末尾にハッシュが付加されます。これにより、ブラウザは効率的に画像をキャッシュでき、サイトのパフォーマンスが改善されます。

URLを直接記述したい場合は、pathname://プロトコルを利用することで、自動的なアセットリンクを無効化できます。

![バナー](pathname:///img/docusaurus-asset-example-banner.png)

このリンクは、<img src="/img/docusaurus-asset-example-banner.png" alt="バナー" />として生成され、追加の処理やファイルの存在確認は行われません。