본문으로 건너뛰기
버전: Canary 🚧

파일 연결

마크다운 파일에서 직접 파일(예를 들면 docx 파일, 이미지 파일 등)에 연결해야 하는 경우가 있습니다. 이럴 때는 마크다운 파일과 인접한 위치에 파일을 배치하는 것이 편리합니다.

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

# 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

이미지​

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

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

![Example banner](./assets/docusaurus-asset-example-banner.png)

All of the above result in displaying the image:

http://localhost:3000

My image alternative text

노트

@docusaurus/plugin-ideal-image를 사용한다면 문서를 참조해 전용 이미지 컴포넌트를 사용해야 합니다.

파일​

같은 방식으로 require하고 반환된 video나 a 앵커 링크에 있는 URL을 사용해 기존 애셋을 연결할 수 있습니다.

# 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

마크다운 링크는 항상 파일 경로입니다

마크다운 이미지 또는 링크 구문을 사용하는 경우 모든 애셋 경로는 도큐사우루스에 의해 파일 경로로 처리되고 자동으로 require() 호출로 변환됩니다. JSX 구문을 직접 작성해 사용하지 않는 한 마크다운에서 require()를 사용할 필요는 없습니다.

SVG 파일​

도큐사우루스에서는 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

테마 이미지​

도큐사우루스에서는 ThemedImage 컴포넌트(테마에 포함된)를 기반으로 테마 이미지를 조작할 수 있습니다. 이를 통해 현재 설정한 테마에 따라 이미지를 다른 파일로 대체할 수 있습니다.

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
Docusaurus themed imageDocusaurus themed image

깃허브 스타일 테마 이미지​

깃허브는 사용자가 쉽게 구현할 수 있는 경로 조각과 함께 자체적인 이미지 테마 접근 방식을 사용합니다.

경로 조각(깃허브의 경우 #gh-dark-mode-only와 #gh-light-mode-only)을 사용해 이미지 표시 여부를 토글하려면 사용자 지정 CSS에 다음 코드를 추가합니다(깃허브에 연결하고 싶지 않은 경우에는 여러분이 만든 접미사를 사용할 수도 있습니다).

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

Docusaurus themed imageDocusaurus themed image

정적 애셋​

마크다운 링크 또는 이미지가 절대 경로에 있다면 경로는 파이 경로로 표시되며 정적 디렉터리에서 확인할 수 있습니다. 예를 들어 정적 디렉터리를 ['public', 'static']로 구성한 경우 이미지를 처리하는 방식입니다.

my-doc.md
![An image from the static](/img/docusaurus.png)

도큐사우루스는 static/img/docusaurus.png와 public/img/docusaurus.png 파일 모두를 찾으려고 시도할 겁니다. 그럼 링크가 URL로 유지하는 대신 require() 호출로 변환됩니다. 이는 두 가지 측면에서 바람직합니다.

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

URL을 작성하려고 하는 경우 pathname:// 프로토콜을 사용해 자동 애셋 연결을 비활성화할 수 있습니다.

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

링크는 다른 처리나 파일 여부 확인 없이 <img src="/img/docusaurus-asset-example-banner.png" alt="banner" />로 생성됩니다.