설정 사전: Fragments
Fragment 목록, 홈 미리보기, 독립 댓글, 안정적인 링크입니다.
목차
먼저 콘텐츠를 게시하려면 Fragment 게시하기를 읽으세요. 여기는 설정 조회용입니다. 설치·설정 위치는 첫 가이드, 모든 모듈은 설정 사전 시작 페이지에 있습니다.
기본값은 현재 demo가 아닌 테마 패키지 기준입니다. 설정은 모두 src/site.config.ts의 기존 defineThemeConfig({...})에 합치고 theme·i18n을 중복 생성하지 마세요.
수정할 위치부터 찾기
| 바꿀 항목 | 설정 경로·위치 |
|---|---|
| 목록·홈 입구 활성화 | theme.fragments.enabled |
| 전체 목록 페이지당 수 | theme.fragments.pageSize |
| 독립 댓글 | theme.fragments.comments.enabled, 연결은 theme.comments 공유 |
| 제목·설명·안내·닫기 문구 | i18n.locales.<locale>.messages.fragments |
| 번호·페이지 이동 | theme.pagination, 문구는 messages.blog |
| ID·시간·제목 | Markdown frontmatter이며 site.config가 아닙니다. |
| 홈 개수·높이·아바타 | 현재 공개 설정 필드 없음 |
theme.fragments.enabled: Fragments 켜기
- 타입 / 기본값: boolean /
false. - 상태 / 역할: 적용됩니다. 켜면
src/content/fragments/<locale>/**/*.md를 읽고 활성 언어의 목록·위치 인덱스를 만듭니다. 해당 언어 내용이 있으면 홈 입구를 표시합니다. - 제한: 끄면 컬렉션을 읽지 않고 목록 라우트도 만들지 않습니다. 파일은 유지합니다. 켰지만 내용이 없으면 빈 목록이며 홈 입구는 없습니다.
.md만 읽고.mdx는 안 됩니다. - 예시:
theme: { fragments: { enabled: true } }.
첫 페이지는 /<locale>/fragments/, 이후는 /<locale>/fragments/2/ 등입니다. /1/을 만들지 마세요. 언어부터 활성화해야 합니다. 다국어 가이드를 참고하세요.
theme.fragments.enabled: false이면 dev, build, prepare-covers/doctor가 Fragments 본문의 이미지 참조를 건너뜁니다. 해당 참조만으로 처리 대상이 되는 이미지는 원본이나 파생 파일이 없어도 됩니다. 다만 글 표지 참조와 src/assets/blog/default-covers/, src/assets/blog/covers/originals/ 이미지 풀은 Fragments 전용 이미지라도 준비와 검증을 계속합니다. 파일을 삭제하지 않으며 다시 켜면 Fragments 이미지 처리를 재개합니다.
버전 안내: 비활성 콘텐츠의 이미지 격리는 0.36.1부터 제공하며 0.36.0에는 없습니다. 이전 버전에서 지원한다고 가정하지 마세요.
theme.fragments.pageSize: 전체 목록 페이지당 수
- 타입 / 기본값: number /
20. - 상태 / 역할: 적용되며 전체 목록과 ID→페이지 위치 인덱스를 제어합니다.
- 제한: 1–100의 안전한 정수여야 합니다. 소수, 0, 음수, 범위 초과는 오류이며 자동 자르지 않습니다. 꺼져 있어도 pageSize는 검증합니다. 홈 최신 세 미리보기는 이 값이나
theme.homeLatestCount에 영향받지 않습니다. - 예시:
theme: { fragments: { pageSize: 10 } }.
언어별 pubDate 최신순이며 시간이 같으면 ID localeCompare로 정렬합니다. 파일 이름 정렬·미래 날짜 제외는 없습니다. 개수를 바꾸면 페이지가 달라지므로 아래 안정적 링크로 공유하세요.
theme.fragments.comments.enabled: Fragment 댓글
- 타입 / 기본값: boolean /
false. - 상태 / 역할: 조건부 적용입니다. 기능이 켜지면 전체 목록 카드에 버튼을 표시하고 공통 팝업에서 해당 토론을 로드합니다. 홈 미리보기에는 버튼이 없습니다.
- 제한: 글 스위치
theme.comments.enabled와 독립적입니다. 공통 Giscus 연결도 필수이며 빠지면 페이지 생성 오류이고 빈 목록으로 우회할 수 없습니다. 서비스·저장소 권한도 올바르게 설정해야 합니다. - 예시:
theme: { fragments: { enabled: true, comments: { enabled: true } } }.
Fragments만 켜고 댓글은 끄는 예시입니다.
theme: {
fragments: {
enabled: true,
pageSize: 10,
comments: { enabled: false },
},
},
Fragment 댓글만 쓴다면 글 스위치는 false여도 되지만 repo, repoId, category, categoryId는 필요합니다. 타입·기본값·검증은 Giscus 연결, 전체 예시는 Fragment 댓글만 켜기에 있습니다. 로컬 검사는 원격 권한·ID를 증명하지 않습니다.
fragment/<stable-id>로 토론을 연결하며 같은 ID 번역은 공유합니다. 글 mapping, term, number, shareAcrossLocales는 쓰지 않습니다. specific, strict '1', emitMetadata '1'을 고정하고 페이지 언어를 따르며 theme.comments.lang은 사용하지 않습니다. 글 댓글도 켜면 그 설정의 검증은 계속 실행합니다.
댓글 테마, 반응, 입력 위치는 Giscus를 공유합니다. 첫 클릭 때 스크립트를 넣으며 고정 eager는 클릭 뒤 즉시 로드이지 첫 화면 미리 로드가 아닙니다. 닫아도 iframe을 유지하고 다른 콘텐츠는 토론을 전환합니다. 약 15초 유효 응답이 없으면 실패·재시도를 표시하며 공개 타임아웃 설정은 없습니다.
Fragment UI 문구: messages.fragments
전체 접두사는 i18n.locales.<locale>.messages.fragments입니다. 모두 string이며 기능이 아닌 문구를 바꿉니다. 내장 현재 언어·대체값을 사용하고 표는 중국어 간체 / 영어 기본값만 나열합니다. 생략은 기본 문구, 빈 문자열은 의도적 덮어쓰기이며 컨트롤 삭제를 보장하지 않습니다. 예시는 한국어이며 fragments 객체 안에 씁니다.
| 필드 | 중국어 간체 / 영어 기본값 | 상태·역할·제한 | 한국어 예시 |
|---|---|---|---|
title |
碎片 / Fragments | 조건부 적용: 목록 제목, 페이지 제목 일부, 홈 입구의 접근 가능한 이름이며 개별 제목은 아닙니다. | title: '짧은 기록' |
description |
沿途记录的几句话。 / Brief thoughts, kept along the way. | 조건부 적용: 목록의 가시 소개·페이지 설명입니다. 홈 팝업에는 소개를 표시하지 않습니다. | description: '일과 일상의 작은 일들을 기록합니다.' |
empty |
还没有碎片。 / No fragments yet. | 조건부 적용: 전체 목록이 비었을 때 안내이며 홈 입구를 강제 표시하지 않습니다. | empty: '나중에 다시 방문해 주세요.' |
comments |
评论 / Comments | 조건부 적용: Fragment 댓글 버튼 문구입니다. | comments: '토론 참여' |
close |
关闭 / Close | 조건부 적용: 댓글 팝업 닫기 문구·홈 창 닫기의 접근 가능한 이름입니다. | close: '창 닫기' |
previous |
上一页 / Previous | 현재 미사용: 타입은 받지만 실제 페이지는 messages.blog.previous를 사용합니다. | previous: '이전 페이지' |
next |
下一页 / Next | 현재 미사용: 타입은 받지만 실제 페이지는 messages.blog.next를 사용합니다. | next: '다음 페이지' |
loading |
正在加载评论… / Loading comments… | 조건부 적용: 댓글 로드 상태입니다. | loading: '토론에 연결하는 중…' |
error |
评论未能加载,请检查网络或评论配置后重试。 / Unable to load comments. Check your network or comment settings, then retry. | 조건부 적용: 댓글 로드 실패이며 위치 인덱스 오류는 아닙니다. | error: '현재 토론을 이용할 수 없습니다. 다시 시도하세요.' |
retry |
重试 / Retry | 조건부 적용: 댓글 실패 뒤 재시도 버튼입니다. | retry: '다시 연결' |
copyLink |
复制碎片链接 / Copy fragment link | 조건부 적용: 공유 링크 버튼 title·접근 가능한 이름이며 스크립트가 활성화합니다. | copyLink: '이 기록 링크 복사' |
linkCopied |
链接已复制 / Link copied | 조건부 적용: 복사 성공 안내입니다. | linkCopied: '복사했습니다' |
copyLinkFailed |
未能自动复制,请复制下方链接。 / Unable to copy automatically. Copy the link below. | 조건부 적용: 클립보드 실패 후 수동 복사 안내입니다. | copyLinkFailed: '이 링크를 직접 복사하세요.' |
notFound |
找不到这条碎片,它可能已被移除。 / Fragment not found. It may have been removed. | 조건부 적용: 안정적 ID 위치 찾기 실패이며 일반 404 문구는 아닙니다. | notFound: '이 기록은 더 이상 존재하지 않습니다.' |
indexError |
暂时无法定位这条碎片,请刷新页面后重试。 / Unable to locate this fragment. Refresh the page and try again. | 조건부 적용: 위치 인덱스 요청·검증 실패입니다. | indexError: '위치를 찾지 못했습니다. 새로고침 후 다시 시도하세요.' |
한국어 제목·설명만 바꾸는 예시입니다.
i18n: {
locales: {
ko: {
messages: {
fragments: {
title: '짧은 기록',
description: '일과 일상의 작은 일들을 기록합니다.',
},
},
},
},
},
Fragments가 사용하는 공통 설정
| 경로 | 기본값·역할 | 제한·예시·전체 설명 |
|---|---|---|
theme.pagination.* |
Blog List의 여덟 페이지 필드·기본값을 공유합니다. | 둘 이상 페이지일 때 표시합니다. 예: theme: { pagination: { windowSize: 5 } }. 페이지 설정 이후 각 절을 참고하세요. |
i18n.locales.<locale>.messages.blog.previous、next、paginationAria、jumpTo、jumpInputLabel、jumpGo |
string, 현재 언어 내장값이며 가시·접근성 문구입니다. | 예: previous: '이전 페이지'. 페이지 문구를 참고하고 같은 fragments 필드는 바꾸지 마세요. |
i18n.locales.<locale>.messages.blog.backToTop |
string, 현재 언어 내장 문구 | 전체 목록 맨 위로 버튼입니다. 예: backToTop: '맨 위로'. 글 UI를 참고하세요. |
i18n.locales.<locale>.messages.home.viewAll |
string, 현재 언어 내장 문구 | 홈 하단 보관함 링크 이름은 Fragment 제목도 함께 씁니다. 예: viewAll: '전체 보기'. 홈 문구를 참고하세요. |
theme.math.enabled |
boolean / true |
현재 페이지 내용에 따라 수식 스타일 필요 여부를 정합니다. 예: theme: { math: { enabled: false } }. 수식 스위치를 참고하세요. |
theme.comments 전체는 Giscus 사전에 있습니다. 글 매핑을 Fragment 설정으로 취급하지 마세요. theme.toc.enabled, 글 OUTPUT, Red Queen은 목록을 제어하지 않으며 Cards/List 전환도 없습니다.
개별 Fragment의 세 frontmatter 필드
src/content/fragments/<locale>/ Markdown 필드이며 site.config에 쓰지 않습니다. 공개 schema는 세 항목뿐이며 추가 호환 필드는 없습니다.
| 필드 | 타입 / 기본값 | 역할·상태·제한 | 예시 |
|---|---|---|---|
id |
string / 없음, 필수 | 적용. ASCII 영문·숫자 정확히 8자리이며 같은 언어에 중복 불가입니다. 링크·댓글이 의존하므로 게시 후 유지하세요. | id: 'aB3dE6gH' |
pubDate |
Date로 변환 가능한 날짜 / 없음, 필수 | 적용. 해석 가능해야 하며 정렬·UTC 표시에 사용합니다. 시간대 있는 ISO 문자열을 권장합니다. | pubDate: '2026-11-13T08:00:00.000Z' |
title |
string, 생략 가능 / 미설정 | 조건부 적용. 목록·홈 카드 제목이며 없어도 게시됩니다. 파일 이름에서 자동 가져오지 않습니다. | title: '오늘의 작은 발견' |
---
id: 'aB3dE6gH'
pubDate: '2026-11-13T08:00:00.000Z'
title: '오늘의 작은 발견'
---
여기에 본문을 씁니다. 이미지와 코드는 Markdown 본문에 직접 넣으세요.
npm run new-fragment -- --locales zh,en은 새 ID와 현재 시간을 공유하는 파일 묶음을 만듭니다. 실행마다 새 ID이므로 기존 번역은 원 ID를 쓰세요. 언어 간 같은 ID는 가능하고 같은 언어 중복은 오류입니다. 파일 이름은 바꿔도 ID는 파일명·번호에 맞춰 바꾸지 마세요. 구형 ID 자동 이전은 없으며 ID 변경은 토론·공유 주소를 바꿉니다.
description, heroImage, tags, draft, 개별 comments 등은 Fragment 소비 논리가 없습니다. 글 frontmatter를 적용하지 마세요. 특히 draft: true도 초안이 아니므로 미공개 내용을 활성 컬렉션에 두지 마세요.
홈 미리보기·이미지·링크의 고정 동작
구현이 정하며 추가 공개 필드는 없습니다.
- 홈 개수: 현재 언어 최신 세 개, 부족하면 실제 수입니다. 하단은 “현재 표시 수 / 현재 언어 전체 수” 보관함 링크입니다. 다른 언어로 보충하지 않습니다.
- 홈 요약: 렌더링 결과에서 텍스트, 첫 유효 HTTP(S) 이미지, 첫 코드 블록을 추출합니다. 텍스트는 Unicode 코드 포인트 최대 180개, 코드는 최대 8줄·800개이며 초과 시 말줄임을 붙입니다. 카드 높이 초과는 숨기고 전체는 목록에 남습니다. 제목은 별도 표시합니다. 완전한 Markdown 렌더링이 아니며 previewCount·previewHeight 설정은 없습니다.
- 이미지: 지원 로컬 이미지는 기존 manifest의 크기·srcset을 쓰지만 원격·미지원은 최적화를 보장하지 않습니다. 목록 페이지 첫 이미지는 eager / high, 나머지는 lazy이며 비동기 디코딩합니다. 원본·크기·검사는 이미지 가이드를 참고하세요. heroImage를 추가할 필요는 없습니다.
- 안정적 링크:
/<locale>/fragments/#<ID>입니다. 스크립트가 인덱스로 현재 페이지를 찾아 필요하면 이동합니다. 콘텐츠·pageSize 변경 후에도 ID 기준이며 삭제·ID 변경은 원 대상을 유지하지 못합니다. JavaScript 없이 일반 페이지 링크는 되지만 페이지 간 자동 위치·복사는 의존할 수 없습니다. - 언어 전환: 대상 언어 첫 목록으로 가며 같은 ID 번역을 바로 찾는다고 보장하지 않습니다.
- 공개 콘텐츠: Markdown 합계 출력은
/<locale>/fragments/index.md입니다. 사이트 검색·글 RSS 활성 스위치가 아니며 공개 콘텐츠에 민감 정보를 넣지 마세요.
아바타, hover 애니메이션, 창 테두리, 코드 높이는 현재 site.config 항목이 아닙니다. 존재하지 않는 설정은 제공하지 않습니다. 설정 시작 페이지에서 다른 모듈을 보세요.