헬프 센터 — 마크다운 문서, 검색, i18n
헬프 센터는 하나의 중요한 요구사항을 가진 작은 정적 사이트입니다: 모든 문서가 접근 가능해야 합니다 — 사이드바에서, 검색에서, 아직 번역되지 않은 로케일에서도 말이죠. 이 모듈을 출시한 엔지니어가 작성했으며, 이전 구현은 마케팅 사이트의 헬프 센터였습니다. 아래 모듈은 이 요구사항을 검증된 속성으로 유지합니다: 사이드바는 모든 카테고리의 모든 문서를 표시하고, 검색은 입력된 방식과 관계없이 쿼리를 랭킹하며, 관련 링크가 확인되지 않으면 검증기가 빌드를 실패시킵니다. 로더, 검색 및 태그 스위트가 각각을 다루며, 기록은 references/provenance.md에 있습니다.
사용 시기
Next.js App Router에서 문서가 저장소의 마크다운 파일인 헬프 센터, 문서 섹션 또는 지식 베이스를 구축하거나 확장할 때(다중 로케일 포함 또는 미포함).
사용하지 말아야 할 때
- 블로그. 날짜가 있고 작성자가 있는 게시물로 커버 이미지와 지역화된 슬러그를 가지는 것은 다른 콘텐츠 모델입니다; 호스트의 블로그 모듈을 유지하세요.
- 코드로 생성된 문서 (OpenAPI, TypeDoc) — 해당 생성기를 사용하고 출력물에 링크하세요.
- CMS 기반 헬프 사이트로 편집자가 런타임에 게시하는 경우 — 인덱스 계약은 여전히 적용되지만, 로더, 정적 파라미터 및 검증이 변경됩니다; extensions.md의 CMS 참고를 확인하세요.
- 마크다운으로 작성된 마케팅 페이지. 호스트의 렌더러를 재사용하세요; 이 모듈은 많은 문서를 위한 탐색, 검색 및 로케일 모델입니다.
아키텍처
content/help/<[locale]/><category>/<slug>.md
│ gray-matter + 정규화
▼
getHelpIndex(locale) ── React cache(): 요청당 한 번 파싱 ──┐
categories · articles (sorted) · byKey · tags · byTag · skipped│
│ │
├─► pages: landing / category / tag / article ── metadata, JSON-LD, canonical/hreflang
├─► HelpShell ── toSummary → nav tree (sidebar + drawer)
│ ── toSearchDoc → HelpSearch (클라이언트, 토큰화된 접두사 검색)
├─► helpSitemapEntries()
└─► validate:help (CI) ── 확인되지 않은 related, order 충돌, 잘못된 날짜, 잘못된 슬러그, 태그 표류
모든 것은 인덱스에서 읽습니다. 그 외에는 파일 시스템에 접근하지 않습니다.
중요 사항
- 파일 시스템이 스키마입니다. 폴더 = 카테고리, 파일명 = 슬러그, 프론트매터는 메타데이터일 뿐입니다. 프론트매터의
slug/category는 경로에 대해 검증되며, 절대 사용되지 않습니다. - 요약만 클라이언트로 전달됩니다.
toSummary/toSearchDoc은 본문을 제거합니다;HelpArticle을 클라이언트 컴포넌트에 전달하면 모든 페이지에 전체 코퍼스가 전송됩니다. - 번역되지 않은 페이지는 중복입니다. 기본 로케일에서 렌더링되고, 탐색에서 제자리를 유지하며, 안내문을 표시하고, 기본 로케일 URL로 표준화되며, hreflang 및 사이트맵에서 제외됩니다.
- 런타임은 관대하지만 CI는 그렇지 않습니다. 잘못된 참조는 무시되고, 누락된 순서는 마지막에 정렬되며 —
validate:help는 작성자에 대해 빌드를 실패시킵니다. - 검색은 설계상 클라이언트 측입니다. 문서당 약 1KB, 이미 탐색을 위해 페이지에 있으며, 첫 입력에 결과를 표시합니다. 본문 검색은 확장 기능입니다.
엄격한 규칙
절대 접을 수 있는 목록의 높이를 제한하지 마세요.
max-h-*+overflow-hidden쌍은 맞지 않는 것은 잘라내고 아무것도 보고하지 않습니다.hidden또는 실제 접을 수 있는 프리미티브를 사용하여 목록이 모든 링크를 렌더링하거나 아무것도 렌더링하지 않도록 하세요.
절대
order만으로 정렬하지 마세요. 충돌 시readdir순서로 넘어가며, 이는 파일 시스템마다 다릅니다. 제목으로 충돌을 해결한 다음, 슬러그로 해결하세요.
절대
related를 검증 없이 확인하지 마세요. 삭제된 참조는 페이지에서 보이지 않습니다; 검증기가 작성자가 슬러그가 변경되었음을 알 수 있는 유일한 곳입니다.
절대 트리밍되지 않은 쿼리를 검색하지 말고, 제목만으로 검색하지 마세요. 트리밍, 토큰화, 발음 구별 부호 접기, 태그 및 제목 포함, 필드별 랭킹을 수행하세요.
절대 i18n 시스템이 있는 호스트에서 크롬 문자열을 하드코딩하지 마세요. 모든 문자열은
HelpStrings를 통해 전달되어 헤더, 푸터 및 안내문이 함께 로케일을 전환합니다.
절대 태그를 철자로 키로 사용하지 마세요. 대소문자, 하이픈 및 복수형은 작성자마다 다릅니다.
tagSlug로 그룹화하여 모든 변형이 한 페이지에 도달하도록 하고, 검증기가 표류를 보고하게 하세요.
빠른 시작
- 심 계약을 채우고 카테고리 ID를 확정하세요 — adaptation.md.
- 콘텐츠 레이아웃을 선택하고 구성을 작성하세요 — content-model.md.
- 로더와 프론트매터 파서를 복사하고, 실제 콘텐츠에 대해 즉시 검증기를 실행하세요 — content-loader.md.
- 문자열과 경로를 호스트의 i18n에 연결하세요 — i18n.md.
- 세 페이지, SEO 도우미 및 사이트맵 항목을 추가하세요 — routes.md — 그런 다음 태그 페이지와 연결된 칩을 추가하세요 — tags.md.
- 셸, 탐색 트리 및 드로어를 구축하세요 — ui.md — 그런 다음 호스트의 프리미티브에서 빵 부스러기, 카드, 목록 및 렌더러를 구축하세요 — ui-content.md.
- 검색 및 훅을 추가하고, 결과 없음 훅을 분석에 연결하세요 — search.md.
- 제공된 테스트를 실행한 다음 동작 계약을 확인하세요: 가장 긴 카테고리가 완전히 접근 가능한지, 후행 공백 쿼리, 악센트 쿼리, 번역되지 않은 페이지의 표준 URL.
참조 디렉터리
| 시나리오 | 트리거 키워드 | 참조 |
|---|---|---|
| 기존 앱에 통합 | adapt, seam, rename categories, host probe, integrate, dependencies | adaptation.md |
| 프론트매터, 폴더, 슬러그, 검증 | frontmatter, slug, category, order, related, updatedAt, featured, validate, CI | content-model.md |
| 파일을 인덱스로 읽기 | loader, gray-matter, cache, fallback, headings, sort, index, fs | content-loader.md |
| 검색 상자 및 랭킹 | search, combobox, ranking, tokenize, diacritics, prefix, keyboard, no results | search.md |
| 태그, 태그 페이지, 칩, 태그 클라우드 | tag, tags, tag page, chip, tag slug, spelling, plural, browse by tag | tags.md |
| 로케일, 문자열, 날짜, 표준 URL | i18n, locale, translation, fallback, hreflang, strings, plural, Intl | i18n.md |
| 페이지, 메타데이터, JSON-LD, 사이트맵 | route, page.tsx, generateStaticParams, dynamicParams, notFound, canonical, TechArticle, sitemap | routes.md |
| 셸, 헤더, 사이드바, 드로어 | layout, sidebar, mobile menu, drawer, collapsible, sticky, HelpShell | ui.md |
| 빵 부스러기, 카드, 목록, 렌더러, 스타일 훅 | breadcrumb, category card, article list, react-markdown, data-help, styling | ui-content.md |
| 출시된 모듈을 넘어서 | full-text, Pagefind, TOC, feedback, git dates, MDX, CMS, redirects | extensions.md |
| 템플릿이 이전 구현과 다른 이유 | provenance, audit, ledger, kept deliberately, fixing the earlier implementation | provenance.md |