설정 사전: Blog List와 태그 목록

$ 게시 2026-11-13 | | 수정 2026-11-14
컨텍스트: 블로그·태그 목록의 실제 필드, 테마 기본값, 범위 제한, 공유 동작, 예시를 설명하고 브라우저 선호와 사이트 설정을 구분합니다.

페이지당 글 수, 태그 스위치, 페이지 번호 창, 이동, 스타일, 목록 UI 문구를 조회합니다.


출력
단어 3.9k 토큰 5.1k

버전 안내: blogPageSize 엄격 검증은 0.36.1부터 제공하며 0.36.0에는 없습니다. 이전 버전에서도 적절한 양의 정수를 입력하세요.

설정 사전 시작 페이지로 돌아가기. 블로그 보관함, 태그 디렉터리, 태그별 글 목록과 공통 페이지 나누기를 다룹니다. 현재 코드가 기준이며 데모의 개수·색상을 기본값으로 취급하지 않습니다.

중국어 간체 블로그는 /zh/blog/, 다음 페이지는 /zh/blog/2/, 태그 디렉터리는 /zh/tags/입니다. 태그별 목록은 페이지의 링크를 쓰세요. 다른 언어는 zh를 바꾸며 기본 언어 홈 주소 모드도 이 경로의 언어 접두사를 제거하지 않습니다.

TypeScript 예시는 src/site.config.ts의 기존 defineThemeConfig에 합칩니다. theme, i18n, pagination이 있으면 내부 필드를 수정하고 다른 설정을 보존하며 같은 객체를 중복 추가하지 마세요.

1. 페이지당 글 수

theme.blogPageSize

  • 타입: number.
  • 테마 기본값: 10.
  • 역할: 블로그·태그 글 목록이 공유하는 페이지당 수입니다. 현재 언어로 고른 뒤 pubDate 최신순으로 정렬합니다.
  • 상태: 적용.
  • 제한: 양의 안전한 정수여야 합니다. 0, 음수, 소수, NaN, Infinity와 안전한 정수 범위를 벗어난 값은 설정 해석 시 명확한 오류가 됩니다. 잘라내거나 기본값으로 자동 복원하지 않으며, 0은 페이지 나누기를 끄는 값이 아닙니다.
  • 범위: 홈 최신 글·Fragment 페이지당 수를 바꾸지 않습니다. 태그 디렉터리 자체도 이 필드로 나누지 않습니다.
theme: { blogPageSize: 12 },

글이 없어도 첫 페이지를 만들며 한 페이지만 있으면 페이지 나누기를 숨깁니다. 개수를 바꾼 뒤 재빌드·재배포해야 합니다. 이전 큰 페이지 번호가 사라질 수 있으며 자동 리다이렉트는 없습니다.

updatedDate, 파일 이름, 조회수가 정렬 기준은 아닙니다. 현재 draft·미래 날짜 필터나 목록 정렬 필드는 없습니다. 첫 글 쓰기를 참고하세요.

2. 태그 입구와 페이지

theme.tags.enabled

  • 타입: boolean.
  • 테마 기본값: true.
  • 역할: 태그 입구, 디렉터리, 태그 글 목록과 카드·본문의 테마 태그 링크를 제어합니다.
  • 상태: 적용.
  • 제한: false는 frontmatter tags, 글, 이전 배포 파일을 삭제하지 않습니다. 블로그를 태그로 필터하는 스위치도 아닙니다. 블로그 바로가기는 현재 언어에 태그가 있어야 하며 켰지만 태그가 없으면 디렉터리는 빈 안내를 표시합니다.
theme: { tags: { enabled: false } },

태그는 frontmatter tags 배열에서 오며 site.config 등록표는 없습니다. 같은 글에서 앞뒤 공백·빈 항목·중복을 정리하지만 대소문자는 구분하여 Astro와 astro를 합치지 않습니다.

디렉터리는 글 수 내림차순, 같으면 태그 문자열순입니다. 특수문자, 중국어, 예약 이름, 긴 태그는 안정적으로 인코딩하므로 생성 링크를 쓰세요. 이름 변경은 경로를 바꿀 수 있으며 이전 주소를 자동 유지하지 않습니다.

카드는 현재 최대 두 태그를 표시하며 개수 설정은 없습니다. 실제 태그 수나 디렉터리의 유효 태그 수집을 제한하지는 않습니다.

3. 페이지 번호 창과 이동

theme.pagination.windowSize

  • 타입: number.
  • 테마 기본값: 7.
  • 역할: 표시할 번호·경계·말줄임에 영향이 있으며 페이지당 글 수는 아닙니다.
  • 상태: 둘 이상 페이지일 때 조건부 적용.
  • 제한: 정상 수치는 내림 후 5–21로 제한합니다. 번호 창 전략이며 모든 숫자·이전·다음·말줄임의 합이 정확히 이 값이라고 보장하지 않습니다. 유한 정수를 쓰세요.

theme.pagination.showJumpThreshold

  • 타입: number.
  • 테마 기본값: 12.
  • 역할: 전체 페이지가 임계값보다 엄격하게 많고 jump.enabled가 true일 때 이동 입력을 허용합니다.
  • 상태: 조건부 적용.
  • 제한: 정상 수치는 내림 후 최소 1입니다. 기본 12페이지에는 없고 13페이지부터 나타납니다. 글 수 임계값이 아니며 0도 무조건 표시가 아닙니다.

theme.pagination.jump.enabled

  • 타입: boolean.
  • 테마 기본값: true.
  • 역할: 이동 폼을 허용합니다.
  • 상태와 제한: 조건부 적용이며 전체 페이지 임계값도 만족해야 합니다. false는 폼만 없애고 번호·이전·다음 링크는 유지합니다. 이동 상호작용은 JavaScript가 필요하지만 일반 링크는 필요 없습니다.

theme.pagination.jump.enterToGo

  • 타입: boolean.
  • 테마 기본값: true.
  • 역할: 입력창 Enter 탐색을 허용합니다.
  • 상태와 제한: 폼이 있을 때 조건부 적용입니다. false는 Enter 제출만 막고 버튼은 남깁니다. 비숫자 문자를 제거하고 실제 번호 범위로 제한하며 임의 URL 이동은 제공하지 않습니다.

함께 설정할 수 있습니다.

theme: {
  pagination: {
    windowSize: 9,
    showJumpThreshold: 8,
    jump: { enabled: true, enterToGo: false },
  },
},

이 동작은 Fragments도 사용하지만 페이지당 수는 자체 pageSize입니다. 특정 태그를 조정한다고 그 태그에만 적용되는 것은 아닙니다.

4. 페이지 나누기 외형 전략

theme.pagination.style.enabled

  • 타입: boolean.
  • 테마 기본값: true.
  • 역할: 컨테이너·번호 버튼의 변형 전략을 켭니다.
  • 상태와 제한: 조건부 적용입니다. false는 기본 변형 1을 쓰며 페이지 나누기 삭제·글 수 변경·전체 Cyberpunk 효과 끄기가 아닙니다. 카드·Cards/List 전환의 무작위 색상도 제어하지 않습니다.

theme.pagination.style.mode

  • 타입: 'random' | 'sequential' | 'fixed'.
  • 테마 기본값: 'random'.
  • 역할: 외형 변형 선택 방식.
  • 상태와 제한: style.enabled가 true일 때 조건부 적용입니다.
모드 현재 동작
random 빌드 시 안정적 초기 변형을 주며 클라이언트 초기화 후 컨테이너·버튼을 다시 무작위 선택합니다. 중복될 수 있고 지속 순환 애니메이션은 아닙니다.
sequential 컨테이너는 페이지 번호, 버튼은 각 순번으로 고릅니다. 버튼 색이 같을 필요 없으며 시간에 따라 순환하지 않습니다.
fixed 컨테이너·버튼 모두 fixedVariant의 같은 변형을 씁니다.

JavaScript가 없으면 정적 HTML의 초기 스타일을 유지하고 클라이언트 무작위 선택을 실행하지 않습니다.

theme.pagination.style.variants

  • 타입: number.
  • 테마 기본값: 9.
  • 역할: 1부터 N까지 선택할 변형 개수입니다. 다중 선택 배열이나 전역 테마 수가 아닙니다.
  • 상태와 제한: 조건부 적용이며 정상 수치는 내림 후 1–12로 제한합니다. 하지만 공유 네온 색상은 현재 1–9만 정의되어 있으므로 10–12를 추가 완전 배색 세 개로 해석하지 마세요. 상속·기본색으로 돌아갈 수 있습니다. 보통 1–9, 기본 9를 권장하며 이 설명이 색상 기능 추가는 아닙니다.

theme.pagination.style.fixedVariant

  • 타입: number.
  • 테마 기본값: 1.
  • 역할: fixed의 변형 번호.
  • 상태와 제한: 조건부 적용입니다. 정상 수치는 내림 후 1부터 현재 variants로 제한합니다. random·sequential의 스타일 고정에는 쓰지 않습니다. 현재 완전 네온 색은 1–9를 권장하며 유한 정수를 쓰세요.

두 번째 외형으로 고정하는 예시입니다.

theme: {
  pagination: {
    style: { enabled: true, mode: 'fixed', variants: 9, fixedVariant: 2 },
  },
},

기본 스타일만 원하면 theme: { pagination: { style: { enabled: false } } }를 합치세요. 필요한 예시만 선택하고 연속 복사해 덮어쓰지 마세요.

5. 목록 제목, 설명, 페이지 문구

전체 접두사는 i18n.locales.<locale>.messages.blog입니다. 모두 선택적 string, 조건부 적용이며 해당 제목·설명·컨트롤이 있을 때 나타납니다. 기본값은 내장 문구·대체값을 해석합니다. 표는 중국어 간체·영어만 나열하며 다른 언어에는 자체 기본값이 있습니다.

필드 중국어 간체 기본값 / 영어 기본값 역할·제한
title 博客 / Blog 첫 블로그 페이지 제목과 숨겨진 영역 제목입니다. 글 제목이나 고정 보기 전환 버튼 문구를 바꾸지 않습니다.
pageTitle 博客 - 第 / Blog - Page 후속 블로그·태그 페이지 제목 접두사입니다. 코드가 번호를 붙이며 사용자 자리표시자는 처리하지 않습니다.
archiveDescription 关于 AI 时代开发、Web 工程与系统架构的文章。 / Essays on AI-era craft, web engineering, and system architecture. 첫 블로그·태그 디렉터리 메타 설명이며 카드 요약은 아닙니다.
pageDescription 博客归档页 / Blog archive page 후속 블로그 메타 설명 접두사이며 코드가 번호와 마침표를 붙입니다. 태그 글 목록의 같은 설명 위치에는 쓰지 않습니다.
i18n: {
  locales: {
    ko: {
      messages: {
        blog: {
          title: '글 보관함',
          pageTitle: '글 보관함 - 페이지',
          archiveDescription: '프로젝트, 독서와 학습 노트.',
          pageDescription: '글 보관함 페이지',
        },
      },
    },
  },
},

페이지 관련 필드도 같은 접두사와 string 타입을 씁니다.

필드 중국어 간체 기본값 / 영어 기본값 역할·제한
previous 上一页 / Previous 이전 링크의 가시 문구·접근 가능한 이름이며 첫 페이지에는 없습니다.
next 下一页 / Next 다음 링크의 가시 문구·접근 가능한 이름이며 마지막 페이지에는 없습니다.
paginationAria 分页导航 / Pagination 페이지 나누기 nav의 접근 가능한 이름이며 추가 대제목은 아닙니다.
jumpTo 跳转到页 / Jump to page 이동 입력 옆 가시 문구이며 폼 조건 충족 시 표시합니다.
jumpInputLabel 页码 / Page number 입력창 숨김 라벨·접근 가능한 이름이며 입력 형식은 바꾸지 않습니다.
jumpGo 跳转 / Go 이동 제출 버튼 문구이며 목적 경로는 바꾸지 않습니다.

태그·Fragments의 공유 페이지 나누기에도 사용합니다. 블로그 라우트는 빈 jumpTo/jumpInputLabel/jumpGo에 영어 대체값이 있지만 태그 라우트는 해석한 값을 직접 전달합니다. 빈 문자열로 여러 페이지의 컨트롤을 숨기지 마세요. jump.enabled를 쓰고 의미 있는 접근 가능한 이름을 유지하세요.

i18n: {
  locales: {
    ko: {
      messages: {
        blog: {
          previous: '이전 페이지',
          next: '다음 페이지',
          paginationAria: '글 페이지 이동',
          jumpTo: '이동할 페이지',
          jumpInputLabel: '대상 페이지 번호',
          jumpGo: '이동',
        },
      },
    },
  },
},

6. 태그 디렉터리와 공유 입구 문구

i18n.locales.<locale>.messages.blog의 선택적 string이며 일반 UI 대체값을 따릅니다. 모두 해당 영역이 있어야 적용합니다.

필드 중국어 간체 기본값 / 영어 기본값 역할·제한
tags 标签 / Tags 태그 입구·디렉터리·목록 제목과 접근 가능한 이름입니다. 실제 태그나 slug는 바꾸지 않습니다.
allPosts 全部文章 / All posts 전체 글로 돌아가는 입구이며 홈 설명에도 씁니다. 전체 수는 바꾸지 않습니다.
noTags 暂无标签 / No tags yet. 유효 태그 없는 디렉터리 안내이며 글 없음 안내는 아닙니다.
taggedPosts 文章 / Posts 태그 글 수의 설명·태그 페이지 설명이며 수동 개수 설정은 아닙니다.
i18n: {
  locales: {
    ko: {
      messages: {
        blog: {
          tags: '태그별로 보기',
          allPosts: '모든 글로 돌아가기',
          noTags: '아직 태그가 없습니다.',
          taggedPosts: '개의 글',
        },
      },
    },
  },
},

문구를 비워도 기능은 꺼지지 않으며 빈 링크·불완전 설명이 남을 수 있습니다. tags 문구를 false·빈 문자열로 바꾸는 대신 theme.tags.enabled로 끄세요.

7. Cards/List, 표지와 나머지 범위

현재 구현 동작이며 새 설정 필드는 아닙니다.

  • 블로그·태그 목록은 Cards/List를 공유합니다. 기록이 없으면 cards이며 JavaScript에서 전환합니다. localStorage의 같은 키로 블로그·태그·언어 간 선택을 공유합니다. 저장소가 안 되어도 전환은 되지만 기억은 보장하지 않습니다.
  • 기본 보기, 전환 끄기, 보기 문구, 열 이름, 카드 색상의 site.config 필드는 없습니다. 전환 버튼·보관함 행은 컴포넌트 내장 언어표를 쓰며 새 언어에 항목이 없으면 영어입니다. messages.blog.title로 바꿀 수 없습니다.
  • 카드는 제목·날짜·표지·최대 두 태그를 표시합니다. 요약 켜기, 표지 우선 후보 수, updatedDate 정렬 설정은 없습니다. 목록 메타 설명 변경으로 description이 카드 요약이 되지는 않습니다.
  • 실제 표지가 있는 앞 두 후보는 eager/high, 나머지는 lazy입니다. List가 표지를 숨겨도 후보 다운로드를 안 한다고 보장하지 않습니다. 이미지 가이드를 참고하세요.
  • 주 블로그 언어 전환은 대상에 같은 페이지 번호가 있으면 유지하고 없으면 첫 페이지로 갑니다. 태그 목록은 같은 태그 문구를 찾아 있으면 그 태그 첫 페이지, 없으면 대상 태그 디렉터리로 갑니다. 태그 번역·동의어 매칭은 하지 않습니다.
  • 홈 최신 글 수·이동 효과는 홈 사전을 참고하세요. 공용 내비게이션, 검색, 푸터, 댓글은 재정의하지 않습니다.

별도 호환 보존할 목록 전용 필드는 발견되지 않았습니다. blogView, showExcerpt, cardTheme를 이미 받는 필드로 간주하지 마세요. 임의 키 추가로 외형 기능이 생기지 않습니다.

변경 후 확인 방법

먼저 dev에서 첫·후속 블로그 페이지, 태그 디렉터리, 태그 목록을 확인하세요. 이동에는 충분한 페이지 수가 필요하고 fixed와 random을 구분하세요. 메타 설명은 head에서, 숨김 라벨·접근 가능한 이름은 큰 글자만 보고 판단하지 마세요.

페이지당 수나 태그를 바꾸면 전체 재빌드·재배포하고 이전 페이지·태그 파일 잔재를 주의하세요. 배포 전 dev를 멈추고 npm run doctor 후 npm run preview로 보세요. doctor가 빌드를 포함하므로 check·build를 반복하지 않아도 됩니다. 설치와 배포 가이드를 참고하세요.