정적 애셋
정적 애셋은 빌드 출력 시 직접 복사되는 코드가 아닌 파일입니다. 이미지, 스타일시트, 파비콘, 글꼴 등을 포함합니다.
By default, you are suggested to put these assets in the static
folder. Every file you put into that directory will be copied into the root of the generated build
folder with the directory hierarchy preserved. 예를 들어 if you add a file named sun.jpg
to the static folder, it will be copied to build/sun.jpg
.
다시 정리하면
- for site
baseUrl: '/'
, the image/static/img/docusaurus.png
will be served at/img/docusaurus.png
. - for site
baseUrl: '/subpath/'
, the image/static/img/docusaurus.png
will be served at/subpath/img/docusaurus.png
.
You can customize the static directory sources in docusaurus.config.js
. For example, we can add public
as another possible path:
export default {
title: 'My site',
staticDirectories: ['public', 'static'],
// ...
};
Now, all files in public
as well as static
will be copied to the build output.
Referencing your static asset
In 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. For the image <img src="/img/docusaurus.png" />
served at https://example.com/test
, the browser will try to resolve it from the URL root, i.e. as https://example.com/img/docusaurus.png
, which will fail because it's actually served at 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.
예시:
import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
<img src={DocusaurusImageUrl} />;
<img src={require('@site/static/img/docusaurus.png').default} />
import useBaseUrl from '@docusaurus/useBaseUrl';
<img src={useBaseUrl('/img/docusaurus.png')} />;
SVG 파일도 가져올 수 있습니다. 가져온 파일은 리액트 컴포넌트로 변환됩니다.
import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;
In Markdown
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. See Markdown static assets.
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>
도큐사우루스는 마크다운 구문에 있는 링크만 구문 분석 처리합니다. If your asset references are using the JSX tag <a>
/ <img>
, nothing will be done.
In CSS
In CSS, the url()
function is commonly used to reference assets like fonts and images. 정적 애셋을 참조하려면 절대 경로를 사용하세요.
@font-face {
font-family: 'Caroline';
src: url('/font/Caroline.otf');
}
The static/font/Caroline.otf
asset will be loaded by the bundler.
One important takeaway: never hardcode your base URL! The base URL is considered an implementation detail and should be easily changeable. URL 슬러그처럼 보이더라도 모든 경로는 실제 파일 경로를 가리킵니다.
URL 슬러그 멘탈 모델이 더 이해하기 쉽다면 다음 경험 법칙을 참고하세요.
- Pretend you have a base URL like
/test/
when writing JSX so you don't use an absolute URL path likesrc="/img/thumbnail.png"
but insteadrequire
the asset. - Pretend it's
/
when writing Markdown or CSS so you always use absolute paths without the base URL.
Caveats
아래 사항에 주의해주세요.
- 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. 적극적인 캐싱과 더 나은 사용자 경험을 위해 좋습니다.
- However, as we've demonstrated above, we are usually able to convert them to
- 절대 경로로 지정해서 누락되는 파일은 컴파일 시 감지되지 않으며 404 에러가 발생합니다.
- By default, GitHub Pages runs published files through Jekyll. Since Jekyll will discard any files that begin with
_
, it is recommended that you disable Jekyll by adding an empty file named.nojekyll
file to yourstatic
directory if you are using GitHub pages for hosting.