전체 텍스트 검색 및 단축키
많은 기술 문서를 뒤져 볼 때 원하는 설정 항목이나 파라미터를 빠르게 찾는 일이 무엇보다 중요합니다. EpoCanvas Docs는 이중 모드 검색을 내장하고 있습니다. 상단 바 검색창은 현재 페이지 안에서 빠르게 위치를 찾아 주고, Ctrl+K 팝업은 사이트 전체 문서를 검색합니다. 두 가지 검색은 모두 브라우저에서 로컬로 처리되며 어떤 백엔드 서비스도 필요로 하지 않으므로, 외부 인터넷이 없는 인트라넷 환경에 사이트가 호스팅되어 있어도 동일하게 사용할 수 있습니다.
두 가지 검색을 각각 언제 사용하나요?
| 상황 | 사용할 검색 | 조작 방법 |
|---|---|---|
| 내용이 지금 이 글 안에 있다는 것을 기억할 때 | 페이지 내 찾기 | 상단 바 검색창을 클릭하고 키워드 입력 |
| 내용이 어느 글에 있는지 확실하지 않아 사이트 전체에서 찾을 때 | 사이트 전체 검색 | Ctrl + K (Mac은 Cmd + K) 누르기 |
페이지 내 찾기: 상단 바 검색창
페이지 상단 가운데의 검색창(돋보기 아이콘)을 클릭하고 키워드를 바로 입력합니다:
그림: 상단 바 검색창에 「배포」를 입력한 뒤의 실제 주석 효과. ① 상단 바 입력창, ② 매칭 카운트(현재 N번째 / 총 M개), ③ 이전 / 다음 이동 버튼, ④ 지우기 버튼, ⑤ 현재 페이지에서 매칭된 모든 텍스트가 자동으로 하이라이트됨.
키워드 입력
한국어 단어(예: 「배포」, 「컴포넌트」), 영어 단어, 코드 조각(예: pnpm, astro.config.mjs)을 지원합니다. 입력하는 동안 현재 페이지에서 매칭된 모든 텍스트에 즉시 하이라이트 배경이 채워지고, 페이지가 자동으로 첫 번째 매칭 위치로 스크롤됩니다.
매칭 결과 사이를 이동
- Enter를 누르거나 아래 화살표를 클릭하면: 다음 매칭 위치로 이동합니다;
- Shift + Enter를 누르거나 위 화살표를 클릭하면: 이전 매칭 위치로 돌아갑니다;
- 검색창에는
현재 N번째 / 총 M개의 진행 카운트가 실시간으로 표시되어 열람 진행 상황을 언제든 파악할 수 있습니다.
검색 지우고 페이지 복원
Esc를 누르거나 × 버튼을 클릭하면 모든 하이라이트가 지워지고 페이지가 원래 상태로 복원됩니다.
사이트 전체 검색: Ctrl+K 팝업
지금 어떤 페이지에 있든 단축키 Ctrl + K(Mac은 Cmd + K)를 누르거나 검색창 오른쪽의 Ctrl K 배지를 클릭하면, 화면 중앙에 전역 검색 창이 뜹니다:
그림: 팝업에 「배포」를 입력한 뒤의 실제 주석 효과. ① 검색창 오른쪽의 Ctrl K 배지(클릭으로도 팝업을 띄울 수 있음), ② 검색 입력창, ③ 문서별로 그룹화된 결과 목록, 매칭된 키워드는 하이라이트, ④ 하단의 키보드 단축키 안내 바.
키워드 입력
한국어 단어(예: 「배포」, 「컴포넌트」), 영어 단어, 코드 조각(예: pnpm, astro.config.mjs)을 지원합니다. 제목이 매칭된 결과는 가장 앞에 배치됩니다.
결과 목록 둘러보기
결과는 문서별로 그룹화되며, 각 항목에는 문서 제목, 해당 챕터, 키워드가 포함된 문맥 미리보기가 표시되고 매칭 단어는 하이라이트됩니다. 그룹 제목을 클릭하면 해당 문서의 매칭 단락을 펼치거나 접을 수 있습니다.
키보드로 전 과정 완료하기
- ↑ ↓: 결과 사이에서 선택을 이동합니다;
- Enter: 선택한 결과를 열고 해당 단락으로 이동합니다;
- Esc: 팝업을 닫습니다.
전 과정에서 마우스가 필요하지 않습니다.
검색은 왜 이렇게 빠를까요?
그림: 이중 모드 검색의 작동 메커니즘 비교. 왼쪽은 상단 바의 페이지 내 키워드 빠른 위치 찾기, 오른쪽은 Pagefind WASM 기반 사이트 전체 정적 인덱스 검색이며, 둘 모두 완전히 브라우저에서 로컬로 실행됩니다.
많은 웹사이트의 문서 검색은 요청을 원격 서버의 데이터베이스 질의로 보내야 하므로, 네트워크가 좋지 않으면 하염없이 로딩만 기다려야 합니다.
EpoCanvas Docs는 Pagefind 로컬 정적 검색 방식을 사용합니다:
- 빌드 시점에 인덱스 추출:
pnpm run build를 실행하면 시스템이 각 문서의 내용을 자동으로 수집하여 압축된 정적 인덱스 분할 파일 묶음을 생성합니다. - 필요할 때 가볍게 다운로드: 검색창에 글자를 입력하면 브라우저는 해당 문자에 대응하는 인덱스 분할 파일(수 KB에서 수십 KB 수준)만 가져옵니다.
- 로컬 즉시 매칭: 매칭과 정렬이 모두 브라우저에서 로컬로 처리되므로 네트워크 요청 지연이 없고, 외부 인터넷이 없는 인트라넷 환경에서도 온전히 사용할 수 있습니다.
검색 활용 팁
- 단어 분리: 더 정확한 내용을 찾으려면 여러 단어를 공백으로 구분해 입력하세요(예:
Cloudflare 도메인). - 제목 우선 검색: 문서 제목과 챕터 제목이 정렬에서 가장 높은 가중치를 가지며, 제목에 키워드가 매칭된 결과가 가장 앞에 배치됩니다.
- 개발 모드의 제약: 사이트 전체 인덱스는 빌드 시에만 생성되며,
pnpm run dev로 시작한 개발 서버에서는Ctrl+K대화상자가 인덱스를 불러오지 않아 전역 검색을 사용할 수 없습니다. 검색을 확인하려면pnpm run build를 실행한 뒤pnpm run preview로 빌드 결과를 여세요. 페이지 내 찾기는 이 제약을 받지 않습니다.