메인 컨텐츠로 이동
Version: 2.0.0-beta.21 🚧

정적 애셋

Every website needs assets: images, stylesheets, favicons, etc. 기본적으로 애셋은 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
module.exports = {
title: 'My site',
staticDirectories: ['public', 'static'],
// ...
};

이제 public 디렉터리에 있는 파일도 static 디렉터리와 마찬가지로 빌드 출력 위치에 복사됩니다.

정적 애셋 참조하기

JSX

In JSX, you can reference assets from the static folder in your code using absolute URLs, but this is not ideal because changing the site baseUrl will break those links. 이미지의 경우 <img src="/img/docusaurus.png" /> 파일이 https://example.com/test에 있다면 브라우저는 URL 루트를 기준으로 이를 처리하게 됩니다.예를 들어 https://example.com/img/docusaurus.png로 접근하면 이미지를 호출하지 못합니다. 실제 파일은 https://example.com/test/img/docusaurus.png로 접근해야 합니다.

You can import() or require() the static asset (recommended), or use the useBaseUrl utility function: both prepend the baseUrl to paths for you.

Examples:

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 파일도 가져올 수 있습니다. 가져온 파일은 리액트 컴포넌트로 변환됩니다.

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

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

마크다운

In Markdown, you can stick to using absolute paths when writing links or images in Markdown syntax because Docusaurus handles them as require calls instead of URLs when parsing the 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>
use markdown syntax

Docusaurus will only parse links that are in Markdown syntax. If your asset references are using the JSX tag <a> / <img>, nothing will be done.

CSS

In CSS, the url() function is commonly used to reference assets like fonts and images. To reference a static asset, use absolute paths:

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

The static/font/Caroline.otf asset will be loaded by the bundler.

important takeaway

One important takeaway: never hardcode your base URL! The base URL is considered an implementation detail and should be easily changeable. All paths, even when they look like URL slugs, are actually file paths.

If you find the URL slug mental model more understandable, here's a rule of thumb:

  • Pretend you have a base URL like /test/ when writing JSX so you don't use an absolute URL path like src="/img/thumbnail.png" but instead require the asset.
  • Pretend it's / when writing Markdown or CSS so you always use absolute paths without the base URL.

주의 사항

아래 사항에 주의해주세요.

  • By default, none of the files in the static folder will be post-processed, hashed, or minified.
    • However, as we've demonstrated above, we are usually able to convert them to require calls for you so they do get processed. This is good for aggressive caching and better user experience.
  • Missing files referenced via hard-coded absolute paths will not be detected at compilation time and will result in a 404 error.
  • 기본적으로 깃허브 페이지는 지킬을 통해 게시된 파일을 실행합니다. 지킬은 _로 시작하는 모든 파일을 삭제합니다. 때문에 파일 호스팅을 위해 깃허브 호스팅을 사용하는 경우에는 static 디렉터리에 .nojekyll라는 이름을 가진 빈 파일을 추가해 지킬을 비활성화하는 것을 권장합니다.