이 블로그를 Astro로 만든 과정

Notes · Written on 2026.11.20 · Updated 2026.11.21 · 2 min read #astro#blog

Astro 5.18로 이 블로그를 만들었다. 한 일을 순서대로 적는다.

  1. astro, @astrojs/mdx, @astrojs/rss, @astrojs/sitemap을 설치했다. React 같은 UI 프레임워크는 쓰지 않았다.
  2. 스타일은 Tailwind CSS v4(@tailwindcss/vite)와 직접 쓴 컴포넌트 CSS를 함께 쓴다. 색과 글꼴 토큰은 global.css의 @theme 한 곳에 둔다.
  3. src/content.config.ts에 posts, study 두 컬렉션을 정의했다. 두 컬렉션은 같은 zod 스키마(title, description, date, updated, tags, draft, topic, series, seriesOrder, featured, cover)를 쓴다.
  4. draft: true인 글은 getCollection의 필터로 빌드에서 뺐다.
  5. 검색은 Pagefind를 쓴다. astro build 뒤에 pagefind --site dist를 실행해 정적 인덱스를 만든다.
  6. 코드 블록은 Astro 내장 Shiki의 dual theme(github-light, github-dark)을 쓰고, 다크 모드일 때 CSS 변수 --shiki-dark로 글자색을 바꾼다. 파일명 머리줄과 줄 강조는 Shiki transformer로 붙였다.
  7. 글마다 OG 이미지(1200×630)를 빌드 때 만든다. satori로 SVG를 만들고 @resvg/resvg-js로 PNG로 바꾼다.
  8. 페이지 전환은 Astro의 <ClientRouter />를 쓴다.
  9. 배포는 withastro/action과 actions/deploy-pages를 쓰는 GitHub Actions 워크플로로 준비했다.

아래 두 코드는 발췌이다. astro.config.mjs에서는 import 문, 주석, OG 이미지용 vite 설정을 뺐고, package.json에서는 build 스크립트만 남겼다.

astro.config.mjs
export default defineConfig({
  site: 'https://d15m4s.github.io',
  integrations: [mdx(), sitemap({ filter: (page) => !/\/(posts|study)\/$|\/category\//.test(page) })],
  markdown: {
    shikiConfig: {
      themes: { light: 'github-light', dark: 'github-dark' },
      wrap: false,
      transformers: [codeBlock()],
    },
    remarkRehype: {
      footnoteLabel: '각주',
      footnoteLabelProperties: { className: ['footnote-label'] },
      footnoteBackLabel: '본문으로 돌아가기',
    },
  },
  vite: {
    plugins: [tailwindcss()],
  },
});
package.json
{
  "scripts": {
    "build": "astro build && pagefind --site dist"
  }
}
Esc