정적 애셋

모든 웹 사이트는 이미지나 스타일시트, 파비콘 같은 애셋(asset)이 필요합니다. 이런 파일을 위해 프로젝트 루트 경로 아래에 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 경로로 복사됩니다.

정적 애셋 참조하기

절대 경로를 사용해 static 디렉터리에 있는 애셋을 참조할 수 있습니다. 하지만 사이트의 baseUrl 설정을 변경하면 연결된 링크가 깨질 수 있어서 적절한 방법은 아닙니다.

대신 import / require()를 사용해 정적 애셋을 참조할 수 있습니다(권장하는 방법입니다). 또는 useBaseUrl 유틸 함수를 사용할 수 있습니다. 두 방법 모두 경로 앞에 baseUrl 설정값을 추가해줍니다.

JSX 예제

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" />;

마크다운 예제

static 디렉터리에 있는 애셋을 참조하는 마크다운 링크나 이미지는 require("@site/static/assetName.png")" 구문으로 변환되고 baseUrl 설정값이 자동으로 경로 앞에 추가됩니다.

my-doc.md

![Docusaurus](/img/docusaurus.png)

MDX 덕분에 useBaseUrl 유틸 함수를 마크다운 파일 내에서 사용할 수 있습니다! 마크다운에서 이미지 참조 시 사용하는 구문 대신 <img> 같은 HTML 태그를 사용해야 합니다. 구문은 JSX에서 사용하는 것과 같습니다.

my-doc.mdx

---id: my-doctitle: My Doc---
// 선언부 영역(front matter) 바로 아래 파일 시작 부분에 구문을 추가합니다.import useBaseUrl from '@docusaurus/useBaseUrl';
...
<img alt="Docusaurus with Keytar" src={useBaseUrl('/img/docusaurus_keytar.svg')} />

주의 사항

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

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