Astro 블로그에 로고와 파비콘 붙이기

2026-10-25 · astro, css, favicon, branding, web

블로그에 로고와 파비콘을 붙였다. 로고 패키지를 받은 뒤 사이트에 연결하기까지 한 과정을 정리한다.

배경

로고 패키지에는 라이트/다크 워드마크, 정사각형 아이콘, .ico 파비콘이 들어 있었다. 이 가운데 사이트에서 실제로 쓸 파일만 골라 붙이는 것이 목표였다.

정적 파일은 `public/`에 둔다

Astro는 src/ 아래 파일을 주소로 서비스하지 않는다. 그래서 쓸 파일만 public/에 복사했다. HTML에서는 public/ 기준 주소를 쓴다.

public/
├── favicon.ico
├── apple-touch-icon.png
└── brand/
    ├── techlog-icon.svg
    ├── logo-light.png
    ├── logo-dark.png
    └── og-image.png

원본 패키지 폴더 전체를 커밋하지 않고, 실제로 쓰는 파일만 커밋했다.

헤더 로고는 테마에 맞춰 둘 중 하나만 보이게

사이트 색 테마는 prefers-color-scheme으로 정해진다. 로고도 같은 기준으로 맞췄다. 라이트용과 다크용 이미지를 모두 넣고, CSS로 한쪽만 보이게 했다.

.site-logo .logo-dark {
  display: none;
}
@media (prefers-color-scheme: dark) {
  .site-logo .logo-light {
    display: none;
  }
  .site-logo .logo-dark {
    display: inline-block;
  }
}

기존 헤더 텍스트와 뒤의 점(::after)은 지웠다.

파비콘과 공유 이미지 태그

BaseLayout.astro의 <head>에 파비콘 링크를 넣었다.

<link rel="icon" href="/favicon.ico" sizes="any" />
<link rel="icon" type="image/svg+xml" href="/brand/techlog-icon.svg" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />

공유 미리보기 이미지(og:image)는 절대 주소가 필요하다. 그래서 SITE_URL이 있을 때만 출력하도록 했다. 임시 주소를 정식 주소처럼 박지 않기 위해서다. 임시로 SITE_URL=https://example.com을 넣고 빌드해서 og:image와 twitter:card가 나오는 것을 확인했다. 브라우저에서 미리보기가 어떻게 보이는지는 미확인이다.

짧은 목록에서 레이아웃이 좌우로 밀리는 문제

글이 몇 편 없는 목록 페이지에는 스크롤이 생기지 않는다. 그런데 Windows 크롬에서는 스크롤바가 없을 때와 있을 때 본문 폭이 달라진다. 그래서 페이지를 오갈 때 내용이 좌우로 덜거덕거렸다.

해결은 스크롤바 자리를 항상 잡아 두는 것이다.

html {
  overflow-y: scroll;
}

macOS처럼 스크롤바가 평소에 숨는 환경에서는 이 설정이 눈에 띄는 차이를 만들지 않는다. scrollbar-gutter: stable도 같은 효과를 낸다. 다만 이 글을 쓸 때는 적용하지 않았다.

헷갈렸던 점들

빌드가 Astro 버전 검사에서 멈춤: 증상은 Node.js v22.22.1 is not supported by Astro! ... ">=22.23.4"였다. 원인은 시스템 Node가 프로젝트가 요구하는 22.23.4보다 낮았기 때문이다. npm i -g nodejs는 시스템 Node를 올려 주지 않는다. nvm을 설치한 뒤 nvm install 22.23.4로 버전을 맞추고, 저장소의 .nvmrc를 따르도록 nvm use를 쓰니 해결됐다.
빌드 중 모듈을 찾지 못함: @astrojs/sitemap이 node_modules에 없었다. package.json에 선언된 의존성이므로 npm install로 해결했다.
개발 서버를 잘못 띄움: worker/ 폴더에서 npm run dev를 돌리면 주제 입력 폼만 나온다. 블로그 디자인을 보려면 저장소 루트에서 npm run dev를 실행하고 localhost:4321을 열어야 한다.

정리

Astro에서 주소로 제공할 정적 파일은 src/가 아니라 public/에 둔다.
테마별 로고는 prefers-color-scheme 기준으로 두 장을 CSS로 번갈아 보이게 한다.
파비콘 링크는 <head>에 넣고, og:image는 SITE_URL이 있을 때만 출력한다.
짧은 목록의 좌우 흔들림은 html { overflow-y: scroll; }로 막는다. 실제 Windows 크롬에서의 확인은 아직 남아 있다.
Node 버전은 .nvmrc에 맞춰 nvm으로 관리한다.