MkDocs 사이트를 배포한 뒤 브라우저 탭에 브랜드 아이콘 대신 일반 문서 아이콘이 계속 표시된 적이 있다면, 흔한 상황입니다. MkDocs는 정적 HTML을 생성하지만 favicon의 위치를 알려 주지 않으면 favicon을 자동으로 적용하지 않습니다. 이 가이드에서는 MkDocs 프로젝트에 favicon을 추가하는 방법을 단계별로 살펴봅니다.
favicon 파일 배치, HTML 태그, 개발자들이 자주 겪는 함정을 함께 살펴봅니다. 과정을 끝내면 모든 브라우저 탭에 선명한 아이콘이 표시됩니다.
사전 준비 사항
시작하기 전에 다음 사항을 준비했는지 확인하세요.
- 설정되어 있으며 로컬에서 빌드되는 MkDocs 프로젝트
mkdocs.yml구성 파일에 접근할 수 있는 권한- favicon용 이미지 파일(PNG 또는 SVG 권장). 필요하면 /에서 Mzu favicondl로 생성할 수 있습니다.
1단계: favicon 파일 준비
MkDocs는 기본적으로 docs/ 디렉터리에서 정적 파일을 제공합니다. docs/ 안에 img 폴더가 없다면 만들고 favicon 파일을 넣으세요. 가장 넓은 호환성을 위해 32x32 PNG 또는 SVG를 사용하세요. 구형 브라우저도 지원하려면 사이트 루트에 favicon.ico를 추가하세요.
구성 구조는 다음과 같아야 합니다.
docs/
index.md
img/
favicon.png
favicon.ico (optional, for legacy browsers)2단계: favicon을 사용하도록 MkDocs 구성
MkDocs는 테마를 사용해 페이지를 렌더링합니다. 기본 ‘mkdocs’ 테마와 Material for MkDocs 같은 인기 테마는 대부분 mkdocs.yml의 theme 구성을 통해 favicon을 지정할 수 있습니다.
mkdocs.yml을 열고 theme 구성을 추가하거나 수정하세요.
theme:
name: material
favicon: img/favicon.png기본 테마를 사용하는 경우 구성은 다음과 같을 수 있습니다.
theme:
name: mkdocs
favicon: img/favicon.png이렇게 설정하면 MkDocs가 HTML head에 적절한 <link> 태그를 포함합니다. 정확한 동작은 테마에 따라 다르지만 대부분의 테마는 이 방식을 따릅니다.
3단계: 대체 favicon.ico 추가(선택 사항)
일부 브라우저, 특히 오래된 브라우저는 기본적으로 /favicon.ico를 요청합니다. 404 오류를 피하려면 docs/ 디렉터리의 루트에 favicon.ico 파일을 배치하세요. MkDocs는 이 파일을 빌드된 사이트의 루트로 복사합니다.
PNG 파일은 온라인 변환기나 ImageMagick 같은 도구를 사용해 ICO 파일로 변환할 수 있습니다. 자세한 절차는 PNG에서 ICO로 변환하는 방법 안내에서 확인하세요.
4단계: 빌드 및 확인
mkdocs build 또는 mkdocs serve를 실행해 사이트를 빌드합니다. 브라우저에서 사이트를 열고 탭을 확인하세요. favicon이 표시되어야 합니다. 표시되지 않는다면 페이지 소스를 검사해 <link rel='icon'> 태그가 존재하는지, 올바른 경로를 가리키는지 확인하세요.
더 자세히 확인하려면 브라우저의 개발자 도구를 사용하세요. Network 탭으로 이동해 favicon 요청을 찾습니다. 200 상태는 정상적으로 로드되고 있음을 의미합니다.
자주 발생하는 문제
- 잘못된 파일 경로:
mkdocs.yml의 경로는docs/디렉터리를 기준으로 상대 경로입니다. favicon을docs/img/favicon.png에 배치했다면img/favicon.png를 사용하세요. - 테마 오버라이드: custom theme을 사용하는 경우 템플릿에 link 태그를 직접 추가해야 할 수 있습니다. 해당 테마의 문서를 확인하세요.
- 캐싱: 브라우저는 favicon을 강하게 캐시합니다. favicon을 업데이트한 뒤에는 hard refresh(Ctrl+F5)를 수행하거나 캐시를 지우세요. 자세한 내용은 favicon 캐시 삭제 방법에서 확인하세요.
- ICO 파일 누락:
favicon.ico를 제공하지 않으면 일부 브라우저의 콘솔에 404 오류가 표시됩니다. serious한 문제는 아니지만 피할 수 있습니다.
마무리
파일을 배치할 위치와 theme 설정 방법을 알고 나면 MkDocs에 favicon을 추가하는 일은 간단합니다. 위 단계를 따르면 사용자가 탭에서 문서 사이트를 즉시 식별할 수 있어 전문적인印象을 더할 수 있습니다. 서로 다른 브라우저에서 테스트하고, 성능을 위해 favicon 파일 크기를 합리적인 수준으로 유지하는 것도 잊지 마세요.
문서화된 요구 사항 확인
HTML Standard는 rel='icon'을 현재 페이지를 나타내는 아이콘의 link relationship로 정의합니다.