설정 사전: Blog List와 태그 목록
페이지당 글 수, 태그 스위치, 페이지 번호 창, 이동, 스타일, 목록 UI 문구를 조회합니다.
목차
버전 안내: 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를 반복하지 않아도 됩니다. 설치와 배포 가이드를 참고하세요.