파일 연결

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.

다음과 같은 파일 구조를 가정해보겠습니다.

# Your doc
/website/docs/myFeature.mdx

# Some assets you want to use
/website/docs/assets/docusaurus-asset-example-banner.png
/website/docs/assets/docusaurus-asset-example.docx

Images

이미지는 마크다운 기본 문법, CJS require, ES imports 구문을 사용하는 3가지 방법으로 연결할 수 있습니다.

Markdown syntax

간단한 마크다운 기본 문법을 사용해 이미지를 표시합니다.

![Example banner](./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="Example banner"
/>

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

도큐사우루스에서는 SVG 파일을 바로 사용할 수 있습니다.

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;

http://localhost:3000

이런 사용법은 CSS를 사용해 SVG 이미지 일부를 변경할 때 유용하게 활용할 수 있습니다. 예를 들어 현재 설정한 테마에 따라 SVG 이미지 색상을 변경할 수 있습니다.

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 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

마크다운 링크 또는 이미지가 절대 경로에 있다면 경로는 파이 경로로 표시되며 정적 디렉터리에서 확인할 수 있습니다. 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. The link will then be converted to a require() call instead of staying as a URL. 이는 두 가지 측면에서 바람직합니다.

1. 도큐사우루스가 애셋을 제공할 때 처리할 기본 URL에 대해 걱정할 필요가 없습니다.
2. 이미지가 Webpack의 빌드 파이프라인에 들어가 해당 이름에 해시가 추가되고 브라우저에서 이미지를 캐시해 사이트 성능을 향상시킬 수 있습니다.

If you intend to write URLs, you can use the pathname:// protocol to disable automatic asset linking.

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

This link will be generated as <img src="/img/docusaurus-asset-example-banner.png" alt="banner" />, without any processing or file existence checking.