페이지 레이아웃과 읽기 경험
독자에게 쾌적하고 효율적인 읽기 경험을 제공하기 위해 EpoCanvas Docs는 전통적이면서도 명확한 3단(三欄) 페이지 레이아웃을 채택했습니다. 긴 문서를 읽는 동안에도 언제든 “사이트 전체에서 지금 어디에 있는지”와 “이 글의 어느 절을 읽고 있는지”를 파악할 수 있습니다.
화면 영역 구성 안내
아무 문서나 열면 페이지는 네 개의 주요 기능 영역으로 나뉩니다:
그림: 「렌더링 규칙 상세」 페이지를 예로 든 3단 레이아웃 주석 다이어그램. ① 상단 전역 내비게이션 바, ② 왼쪽 카테고리 목차, ③ 가운데 본문 읽기 영역, ④ 오른쪽 「이 페이지의 목차」 아웃라인. 네 영역은 그림에서 테두리와 번호로 표시되어 있습니다.
그림: 3단 레이아웃의 구조를 보여 주며 각 영역의 이름과 역할을 표시한 구성도.
1. 상단 전역 내비게이션 바 (Header)
페이지 맨 위에 고정되어 떠 있으며, 아래로 스크롤해도 항상 보이고 높이는 3.5rem입니다. 상단 바에는 왼쪽부터 오른쪽 순서로 다음 요소들이 배치되어 있습니다(아래 주석 이미지 참조):
그림: 상단 바 요소 주석 클로즈업. ① 로고와 사이트 이름, ② 전역 검색창, ③ 메인 내비게이션 버튼 그룹, ④ 버전 배지, ⑤ 언어 전환기, ⑥ 라이트/다크 테마 전환, ⑦ GitHub 저장소 링크, ⑧ Telegram 커뮤니티 링크.
- 사이트 로고와 제목(①): 왼쪽에 EpoCanvas 아이콘과 프로젝트 이름을 표시하며, 클릭하면 문서 사이트 홈으로 빠르게 이동합니다.
- 전역 검색창(②): 검색창에 키워드를 입력하면 현재 페이지 내용을 바로 찾을 수 있습니다.
Ctrl+K/Cmd+K를 누르면 사이트 전체 검색 팝업이 열리며, 자세한 내용은 전체 텍스트 검색 및 단축키를 참조하세요. - 메인 내비게이션 버튼(③): “홈”, “제품 소개”, “빠른 시작” 등 자주 쓰는 기능으로 바로 이동하는 링크를 제공하며, 현재 머무는 섹션은 자동으로 강조됩니다.
- 버전 배지(④): 현재 문서가 대응하는 릴리스 버전(예:
v1.2.0)을 표시하며, 클릭하면 GitHub의 상세 업데이트 기록을 볼 수 있습니다. - 다국어 전환기(⑤): 언어 버튼을 클릭하면 10가지 언어가 펼쳐지며, 선택하면 같은 글의 해당 언어 버전으로 이동하고 내비게이션, 사이드바, 본문이 함께 전환됩니다.
- 라이트/다크 테마 전환(⑥): 해/달 아이콘을 제공하여 라이트 모드와 다크 모드 사이를 전환합니다.
- GitHub와 Telegram(⑦⑧): 오른쪽 아이콘은 각각 오픈소스 저장소와 기술 커뮤니티로 이동합니다.
2. 왼쪽 카테고리 목차 (Sidebar)
페이지 왼쪽(너비 16.5rem, 약 264픽셀)에 위치하며 논리적 계층 구조로 모든 문서 챕터를 보여 줍니다:
- 그룹 접기/펼치기: 문서는 “제품 개요 및 시작하기”, “핵심 기능 및 사용 가이드” 등의 그룹으로 정리되어 있으며, 그룹 이름을 클릭하면 펼치거나 접을 수 있습니다.
- 현재 페이지 강조: 현재 읽고 있는 글은 왼쪽 메뉴에서 테마 색 캡슐 배경으로 강조됩니다.
- 스크롤 위치 기억: 한 글에서 다른 글로 이동할 때 왼쪽 사이드바의 스크롤바 위치가 그대로 유지되며 맨 위로 튀지 않습니다.
3. 가운데 본문 읽기 영역 (Main Content)
화면 중앙에 위치하며 기술 문서 내용을 담는 핵심 영역입니다:
- 페이지 제목과 업데이트 시간: 본문 상단에는 글 제목(Frontmatter의
title필드에서 가져옴)과 “마지막 업데이트” 날짜가 표시되어 내용의 최신 여부를 판단하기 쉽습니다. - 적절한 읽기 폭: 본문 영역의 최대 너비는
60rem으로 제한되어, 모니터가 너무 넓어 한 줄이 지나치게 길어지는 것을 막고 읽다가 줄이 바뀌는 일을 방지합니다. - 하단 페이지 이동 링크: 각 문서 끝에는 “이전 글”과 “다음 글” 링크가 자동 생성되어 사이드바 순서대로 이어서 읽을 수 있습니다.
- 코드 블록 복사 버튼: 각 코드 블록 오른쪽 위에는 복사 버튼이 있어 한 번의 클릭으로 코드 원문을 복사할 수 있습니다.
4. 오른쪽 문서 아웃라인 (Table of Contents)
본문 오른쪽에 위치합니다:
- 제목 자동 수집: 시스템이 페이지를 렌더링할 때 현재 문서의 2단계 제목(
##)과 3단계 제목(###)을 자동으로 분석하여 「이 페이지의 목차」를 생성합니다. - 따라오는 하이라이트 추적: 읽는 동안 페이지를 아래로 스크롤하면 아웃라인이 현재 읽고 있는 절을 자동으로 강조합니다.
- 클릭 시 부드럽게 이동: 아웃라인의 아무 소제목이나 클릭하면 페이지가 해당 단락으로 부드럽게 스크롤되고 주소창 앵커(예:
#화면-영역-구성-안내)가 갱신되어 복사·공유하기 편리합니다.
라이트 모드와 다크 모드
EpoCanvas Docs는 라이트 테마와 다크 테마를 동시에 제공하며, 두 가지 색 구성은 모두 src/styles/custom.css의 CSS 변수로 정의됩니다:
- 시스템 설정 따르기: 웹페이지를 처음 열면 사이트가 운영체제의 라이트/다크 설정을 감지하여 대응되는 테마로 표시합니다.
- 수동 전환 및 기억: 상단 바의 테마 전환 버튼으로 수동 전환할 수 있으며, 선택 결과는 브라우저 LocalStorage에 저장되어 다음에 열어도 유지됩니다.
그림: 같은 사이트가 라이트 모드에서 표시되는 모습(빠른 시작 페이지를 예로 함).
휴대폰과 태블릿 반응형 대응
휴대폰이나 태블릿 등 크기가 다른 화면에서는 페이지가 화면 크기에 맞춰 레이아웃을 자동으로 조정합니다:
| 기기 유형 | 화면 너비 | 레이아웃 동작 |
|---|---|---|
| 넓은 데스크톱 / 노트북 | >= 1152px | 표준 3단 레이아웃(왼쪽 메뉴 + 가운데 본문 + 오른쪽 아웃라인)을 온전히 표시합니다. |
| 태블릿 / 좁은 창 | 800px ~ 1152px | 오른쪽 아웃라인을 숨기고 왼쪽 내비게이션과 본문의 2단 레이아웃을 유지합니다. |
| 스마트폰 | < 800px | 양쪽 사이드바를 모두 접고 본문을 전체 폭으로 표시합니다. 상단 바의 메뉴 버튼을 누르면 사이드바 서랍이 슬라이드로 열립니다. |
초광폭 모니터를 사용하든 휴대폰에서 잠시 확인하든, 자연스럽고 편안한 읽기 경험을 얻을 수 있습니다.