Docusaurus favicon 설정 가이드

favicon을 교체한 뒤에도 Docusaurus의 기본 아이콘이 계속 표시된다면, 파일이 잘못된 폴더에 있거나 설정이 해당 파일을 가리키지 않을 수 있습니다. favicon을 static/에 놓고 설정 값 하나만 지정한 다음 빌드 결과를 확인하면 됩니다.

사전 준비

다음이 필요합니다.

16×16 픽셀에서도 표식이 식별 가능한 PNG 또는 SVG
프로젝트 의존성을 설치하고, 저장소 루트에서 터미널을 열어 둔 상태

Docusaurus favicon 추가하기: 5단계

적합한 파일을 생성합니다. 정사각형 PNG 또는 SVG를 ICO로 변환하는 데 Mzu favicondl을 사용한 다음 SVG 또는 PNG를 다운로드하세요. 원본 artwork는 단순하게 유지하세요. 전체 wordmark는 탭에서 읽기 어려워집니다.
static/ 디렉터리를 사용합니다. Docusaurus는 내부 경로를 변경하지 않고 static/ 디렉터리를 빌드 출력으로 복사합니다. 기본 아이콘을 교체하거나, 다음과 같이 파일을 배치하세요.
```
static/
└── img/
    ├── favicon.ico
    ├── favicon.svg
    └── favicon-32.png
```
Docusaurus 내장 설정 옵션을 지정합니다. docusaurus.config.ts의 기존 객체에 다음 구문을 유지하거나 추가하세요.
```
const config: Config = {
  // ...other options
  favicon: 'img/favicon.ico',
};
```
static/ 기준의 상대 경로를 사용하고, 맨 앞에 slash를 붙이지 마세요. 내장 옵션이 아이콘 링크를 추가하고 baseUrl을 적용하므로 도메인 루트나 하위 경로 모두에서 설정이 작동합니다.
크기에 따라 확대되는 아이콘이 필요하면 SVG를 추가합니다. ICO fallback을 그대로 유지하면서 동일한 config 객체에 다음 속성을 추가하세요.
```
headTags: [
  {
    tagName: 'link',
    attributes: {
      rel: 'icon',
      type: 'image/svg+xml',
      href: '/img/favicon.svg',
    },
  },
],
```
이 태그는 HTML의 rel='icon' link relationship를 따릅니다. headTags는 literal로 처리되므로 base path를 포함해야 합니다. baseUrl: '/docs/'인 경우 /docs/img/favicon.svg를 사용하세요.
빌드하고 실제 output을 확인합니다. 다음 명령을 실행하세요.
```
npm run build
npm run serve
```
렌더링된 <head>를 확인하세요. 다음과 같은 icon link가 포함되어야 합니다.
```
<link rel='icon' href='/img/favicon.ico'>
```
build/img/favicon.ico가 존재하는지 확인하고, Network panel이 HTML이 아닌 image을 반환하는지 확인하세요. baseUrl을 사용하는 경우 prefix가 적용된 URL도 확인하세요. 전체 build/ 디렉터리를 배포하세요.

흔히 빠지기 쉬운 함정

src/img에 파일 넣기: import된 asset은 app에서 bundling되지만, 자동으로 /img/에 게시되지는 않습니다. 이 설정에서는 static/를 사용하세요.
baseUrl 무시하기: config option이 이를 처리하지만, headTags에 직접 입력한 icon URL은 처리하지 않습니다.
캐시된 탭 확인하기: 사이트를 private window에서 열거나 강제로 reload하세요. 응답이 올바른데도 탭에 이전 상태가 남아 있다면 favicon troubleshooting checklist를 사용하세요.
서로 겹치는 icon link: 생성된 head에서 theme 또는 plugin이 추가한 tag를 확인하세요. 의도한 SVG 하나와 ICO fallback 하나만 유지하고, 실수로 중복된 항목은 제거하세요.
더 넓은 범위의 workflow 비교하기: 공통 원칙은 static-site-generator favicon guide와 비교해 확인하세요. Docusaurus에만 해당하는 부분은 favicon option과 static/ output입니다.

결론

Docusaurus favicon에는 page-level component나 plugin이 필요하지 않습니다. 적절한 파일을 생성해 static/img/에 보관하고, favicon이 ICO 파일을 가리키도록 설정하세요. 배포할 때마다 또는 base-path를 변경할 때마다 빌드 결과의 head를 확인하세요.

사전 준비

Docusaurus favicon 추가하기: 5단계

흔히 빠지기 쉬운 함정

결론

Docusaurus용 아이콘 세트를 준비하세요