﻿---
title: "설정 사전: Blog List와 태그 목록"
description: "블로그·태그 목록의 실제 필드, 테마 기본값, 범위 제한, 공유 동작, 예시를 설명하고 브라우저 선호와 사이트 설정을 구분합니다."
url: "https://demo.anglefeint.com/ko/blog/config-blog-list/"
language: "ko"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

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

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

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

중국어 간체 블로그는 `/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 페이지당 수를 바꾸지 않습니다. 태그 디렉터리 자체도 이 필드로 나누지 않습니다.

```ts
theme: { blogPageSize: 12 },
```

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

updatedDate, 파일 이름, 조회수가 정렬 기준은 아닙니다. 현재 draft·미래 날짜 필터나 목록 정렬 필드는 없습니다. [첫 글 쓰기](https://demo.anglefeint.com/ko/blog/starter-guide-2-languages-and-routing/)를 참고하세요.

## 2\. 태그 입구와 페이지

### `theme.tags.enabled`

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

```ts
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 이동은 제공하지 않습니다.

함께 설정할 수 있습니다.

```ts
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를 권장하며 유한 정수를 쓰세요.

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

```ts
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 | 후속 블로그 메타 설명 접두사이며 코드가 번호와 마침표를 붙입니다. 태그 글 목록의 같은 설명 위치에는 쓰지 않습니다. |

```ts
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를 쓰고 의미 있는 접근 가능한 이름을 유지하세요.

```ts
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 | 태그 글 수의 설명·태그 페이지 설명이며 수동 개수 설정은 아닙니다. |

```ts
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가 표지를 숨겨도 후보 다운로드를 안 한다고 보장하지 않습니다. [이미지 가이드](https://demo.anglefeint.com/ko/blog/starter-guide-images/)를 참고하세요.
*   주 블로그 언어 전환은 대상에 같은 페이지 번호가 있으면 유지하고 없으면 첫 페이지로 갑니다. 태그 목록은 같은 태그 문구를 찾아 있으면 그 태그 첫 페이지, 없으면 대상 태그 디렉터리로 갑니다. 태그 번역·동의어 매칭은 하지 않습니다.
*   홈 최신 글 수·이동 효과는 [홈 사전](https://demo.anglefeint.com/ko/blog/config-home/)을 참고하세요. 공용 내비게이션, 검색, 푸터, 댓글은 재정의하지 않습니다.

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

## 변경 후 확인 방법

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

페이지당 수나 태그를 바꾸면 전체 재빌드·재배포하고 이전 페이지·태그 파일 잔재를 주의하세요. 배포 전 dev를 멈추고 npm run doctor 후 npm run preview로 보세요. doctor가 빌드를 포함하므로 check·build를 반복하지 않아도 됩니다. [설치](https://demo.anglefeint.com/ko/blog/starter-guide-1-configure-your-site/)와 [배포](https://demo.anglefeint.com/ko/blog/starter-guide-deployment/) 가이드를 참고하세요.
