docs.crowny.org 문서 상세 페이지 5종 개선

개요

docs.crowny.org 문서 상세 페이지(/docs/:slug)에 5가지 UX 개선을 적용했다.

무엇을 했는지

개선 1: 목차 자동 생성 (TOC)

• 마크다운 ## / ### 제목을 파싱하여 우측 220px 사이드바로 표시
• position: sticky; top: 24px — 스크롤 따라 고정
• 각 제목에 자동으로 id 주입 (ex: h-개요, h-5-tier-공격-체계)
• IntersectionObserver — 현재 뷰포트에 있는 섹션 .active 하이라이트
• TOC 항목 클릭 시 scrollIntoView({behavior:'smooth'}) 부드러운 스크롤
• 제목 2개 미만이면 사이드바 미표시

개선 2: 이전/다음 문서 네비게이션

• 날짜순(파일명 알파벳) 기준 이전/다음 문서 카드
• ← 이전: 제목 / 다음: 제목 → 카드 스타일
• 없으면 투명한 빈 카드로 레이아웃 유지

개선 3: 관련 문서 추천

• 같은 카테고리의 다른 문서 최대 5개 하단 그리드 표시
• 카테고리 판별: slug에서 키워드 매칭 (40+ 매핑)
• 제목 + 날짜 카드

개선 4: 인쇄/복사 버튼

• 메타 바 우측에 위치
• 복사: /api/md/raw/:slug 로 원본 마크다운 가져와 클립보드 복사, 2초 후 원상복구
• 인쇄: window.print() + @media print CSS (네비/툴바/TOC/이전다음 숨김, 다크→화이트 배경)

개선 5: 메타 정보 바

• 편집 툴바 아래에 가로 바
• 카테고리 배지 (민트 뱃지), 날짜, 파일 크기 (KB), 읽기 시간 (글자수÷500분)

레이아웃 구조

page-wrap (max-width: 1200px)
  nav / back / lock-banner / edit-toolbar / version-panel
  meta-bar  ← 개선 5
  bind-badge (프로젝트 바인딩 문서만)
  doc-layout (grid: 1fr 220px)
    main-col
      rendered (마크다운 본문)
      editor-area (편집 모드)
      pn-nav   ← 개선 2
      related-docs  ← 개선 3
    toc (aside)  ← 개선 1
  present-mode (fixed overlay)

관련 파일

• /Users/ef/CrownyDoc/server-docs.js (2343~2681줄 — /docs/:slug 라우트)
• /Users/ef/CrownyDoc/한선씨/서버/문서상세UI.한선 (한선씨 동반 파일)

검증

bashcurl http://localhost:4100/docs/2026-04-13-crowny-spear-초안 | grep 'meta-bar\|toc\|pn-nav\|related-docs\|copyMarkdown'
# 5가지 모두 확인됨

목차 예시: 개요, 방패+창 구조, 5-Tier 공격 체계, Tier 1~5 항목 자동 생성.

잔여 이슈

• 900px 이하 화면에서 TOC 숨김 — 모바일 드로어 TOC 추후 개선 가능
• 관련 문서 알고리즘이 단순 슬러그 키워드 매칭 — 본문 유사도 기반으로 고도화 가능