📖 사이트X 사용설명서

🗺 1. 사이트 개요

사이트X 템플릿은 커뮤니티/블로그형 웹사이트를 빠르게 구축할 수 있도록 설계된 순수 HTML·CSS·JS 기반의 프론트엔드 스타터킷입니다. 외부 라이브러리 의존성이 없어 로딩이 빠르고, 어떤 백엔드(Node.js, Django, Laravel 등)와도 연동할 수 있습니다.

설계 원칙

• 제로 의존성 — CDN·npm 패키지 없이 브라우저만으로 동작합니다.
• API 주석 방식 — 실제 서버 연동이 필요한 모든 자리에 [API: …] 주석이 표시되어 있어 개발자가 즉시 식별하고 구현할 수 있습니다.
• CSS 변수(토큰) 기반 — 색상·간격·폰트를 :root 한 곳에서 수정하면 전체 사이트에 반영됩니다.
• 더미 데이터 분리 — app.js의 MOCK_BOARDS, MOCK_POSTS를 실제 API 호출로 교체하기만 하면 됩니다.

📁 2. 파일 구조

📄 3. 페이지 안내

⚡ 4. 주요 기능

🌙 다크모드

헤더 우측의 ◐ 버튼을 클릭하면 라이트/다크 모드가 전환됩니다. 선택값은 localStorage에 저장되어 재방문 시에도 유지됩니다.

// app.js — 테마 초기화 및 토글
localStorage.getItem("theme")  // "dark" | "light" | null
document.documentElement.setAttribute("data-theme", "dark")

🔍 검색 바

헤더의 검색 입력창에서 Enter를 누르면 현재는 데모 알림이 표시됩니다. 실제 구현 시 GET /api/search?q=… 엔드포인트로 연결하세요.

📊 게시판 타일 그리드 (메인)

renderBoardGrid(selector) 함수가 MOCK_BOARDS 배열을 읽어 아이콘·이름·글 수 카드를 렌더링합니다. 마우스를 올리면 카드가 살짝 위로 떠오르는 호버 효과가 있습니다.

// 실제 API로 교체하는 방법
const res = await fetch("/api/boards");
window.MOCK_BOARDS = await res.json();
renderBoardGrid("#board-grid");

📜 게시글 목록 테이블

renderPostList(selector, limit) 함수가 번호·분류·제목·작성자·날짜·조회·추천 컬럼을 가진 테이블을 생성합니다. 조회 수 상위 3개 게시글에는 자동으로 HOT 뱃지가 붙습니다.

🗂 카테고리 탭 (게시판)

게시판 페이지 내 전체 / 공지 / 일반 / 질문 / 후기 탭으로 구성되어 있습니다. 탭 클릭 시 해당 카테고리 API를 호출해 목록을 갱신하도록 연결하면 됩니다.

📑 페이지네이션

이전(‹)·다음(›) 버튼과 숫자 페이지가 준비되어 있습니다. 현재 페이지는 .active 클래스로 강조됩니다.

👍 추천 / 비추천 / 스크랩 / 신고

게시글 하단 액션 버튼 4종이 있습니다. 각 버튼의 onclick 핸들러에 아래 API를 연결하세요.

• 추천 → POST /api/posts/:id/like
• 비추천 → POST /api/posts/:id/dislike
• 스크랩 → POST /api/posts/:id/scrap
• 신고 → POST /api/posts/:id/report

💬 댓글

댓글 폼(.comment-form-el)과 목록(.comment-list)이 post.html에 포함되어 있습니다. 폼 submit 시 현재는 데모 알림이 표시됩니다.

🔑 소셜 로그인 버튼

login.html에 카카오·네이버·Google 버튼이 준비되어 있습니다. 각 버튼에 OAuth 인증 URL을 href 또는 onclick으로 연결하면 됩니다.

🔌 5. API 연동 포인트

코드 내 [API: …] 주석이 달린 곳이 모두 실제 서버 연동이 필요한 지점입니다.

🎨 6. 디자인 토큰

style.css의 :root 블록에서 CSS 변수를 수정하면 사이트 전체 디자인이 바뀝니다. 다크모드는 [data-theme="dark"] 블록을 수정하세요.

색상 변수

간격(Spacing) 변수

레이아웃 변수

• --container: 1200px — 페이지 최대 너비
• --header-h: 60px — 헤더 높이
• --radius: 8px / --radius-sm: 4px — 모서리 둥글기

반응형 브레이크포인트

• ≤ 960px — 사이드바가 숨겨지고 단일 컬럼 레이아웃으로 전환됩니다.

📢 7. 광고 슬롯

광고 이미지를 교체하거나 Google Ads 코드를 넣을 수 있는 자리가 사전 지정되어 있습니다.

🛠 8. 커스터마이징 가이드

사이트 이름 변경

모든 HTML 파일의 <title> 태그와 .logo 텍스트(사이트X)를 원하는 이름으로 바꾸세요.

게시판 추가/변경

모든 페이지의 .nav-main 내 <li> 항목과, app.js의 MOCK_BOARDS 배열을 수정하면 됩니다.

// app.js — MOCK_BOARDS 예시
window.MOCK_BOARDS = [
  { id: "tech", icon: "💻", name: "개발", count: 0 },
  { id: "life", icon: "🌱", name: "일상", count: 0 },
];

포인트 컬러 변경

style.css의 --accent 값만 바꾸면 버튼·링크·활성 탭 등 모든 강조 색상이 한꺼번에 바뀝니다.

/* style.css */
:root {
  --accent: #e85d04;       /* 원하는 색상으로 교체 */
  --accent-hover: #c44d00;  /* 호버 시 살짝 어두운 색 */
}

본문 콘텐츠 렌더링 (post.html)

.post-body 내부는 서버에서 받은 HTML이 들어오는 자리입니다. 마크다운을 HTML로 변환한 뒤 반드시 DOMPurify 등으로 XSS 필터링을 적용하세요.

// 예시 — 안전한 HTML 삽입
import DOMPurify from "dompurify";
document.querySelector(".post-body").innerHTML =
  DOMPurify.sanitize(markdownToHtml(rawContent));

🚀 9. 배포 체크리스트

실제 서비스 전 아래 항목을 확인하세요.

• 모든 [API: …] 주석 자리에 실제 API 연동 완료
• 더미 데이터(MOCK_BOARDS, MOCK_POSTS)를 서버 응답으로 교체
• 광고 슬롯(.ad-slot)에 실제 광고 코드 삽입
• 로그인 폼 — 실제 인증 로직 연결 (app.js auth-form 핸들러 수정)
• 소셜 로그인 버튼 — OAuth 콜백 URL 등록 및 연결
• 게시글 본문 — DOMPurify 등 XSS 방어 처리
• <title> 및 <meta description> SEO 정보 채우기
• 파비콘(favicon.ico) 추가
• 이미지 최적화 (WebP 변환 권장)
• HTTPS 적용 확인
• 모바일(≤960px) 레이아웃 크로스 브라우저 확인