메인 컨텐츠로 이동
버전: Canary 🚧

정적 애셋

정적 애셋은 빌드 출력 시 직접 복사되는 코드가 아닌 파일입니다. 이미지, 스타일시트, 파비콘, 글꼴 등을 포함합니다.

기본적으로 애셋은 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
export default {
  title: 'My site',
  staticDirectories: ['public', 'static'],
  // ...
};

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

정적 애셋 참조하기​

JSX​

JSX에서는 절대 URL을 사용해 static 디렉터리에 있는 애셋을 참조할 수 있습니다. 하지만 사이트의 baseUrl 설정을 변경하면 연결된 링크가 깨질 수 있어서 적절한 방법은 아닙니다. 이미지의 경우 <img src="/img/docusaurus.png" /> 파일이 https://example.com/test에 있다면 브라우저는 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 파일도 가져올 수 있습니다. 가져온 파일은 리액트 컴포넌트로 변환됩니다.

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

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

마크다운​

마크다운에서는 링크나 이미지를 마크다운 구문 내에서 절대 경로로 사용할 수 있습니다. 도큐사우루스에서 마크다운 구문 분석 시 URL 대신 require 호출로 처리하기 때문입니다. 자세한 내용은 마크다운 정적 애셋을 참고하세요.

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

도큐사우루스는 마크다운 구문에 있는 링크만 구문 분석 처리합니다. 애셋에 대한 참조를 JSX 태그 <a> / <img>로 설정한 경우 아무 작업도 수행되지 않습니다.

CSS​

CSS에서 url() 함수는 일반적으로 글꼴 및 이미지와 같은 애셋을 참조하는데 사용됩니다. 정적 애셋을 참조하려면 절대 경로를 사용하세요.

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

static/font/Caroline.otf 애셋은 번들러에 의해 로드됩니다.

중요한 사항

한 가지 중요한 사항: 절대 base URL을 하드코딩하지 마세요! base URL은 구현 세부 사항으로 간주되며 쉽게 변경할 수 있어야 합니다. URL 슬러그처럼 보이더라도 모든 경로는 실제 파일 경로를 가리킵니다.

URL 슬러그 멘탈 모델이 더 이해하기 쉽다면 다음 경험 법칙을 참고하세요.

  • JSX 작성 시 /test/와 같은 base URL이 있다고 가정하면 src="/img/thumbnail.png" 같은 절대 URL 경로 대신 require 애셋을 사용합니다.
  • 마크다운이나 CSS 작성 시 /를 사용한다면 base URL 없이 항상 절대 경로를 사용합니다.

주의 사항​

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

  • 기본적으로 static 디렉터리 아래에 있는 파일은 처리 과정에서 아무런 처리를 하지 않습니다. 코드를 난독화 또는 최소화 처리도 하지 않습니다.
    • 하지만 위에서 설명한 것처럼 일반적으로 require 호출로 변환해 처리되도록 할 수 있습니다. 적극적인 캐싱과 더 나은 사용자 경험을 위해 좋습니다.
  • 절대 경로로 지정해서 누락되는 파일은 컴파일 시 감지되지 않으며 404 에러가 발생합니다.
  • 기본적으로 깃허브 페이지는 지킬을 통해 게시된 파일을 실행합니다. 지킬은 _로 시작하는 모든 파일을 삭제합니다. 때문에 파일 호스팅을 위해 깃허브 호스팅을 사용하는 경우에는 static 디렉터리에 .nojekyll라는 이름을 가진 빈 파일을 추가해 지킬을 비활성화하는 것을 권장합니다.