제품 소개 및 핵심 가치

최종 업데이트: 2026. 9. 22. / EpoCanvas 공식 아키텍처 사양

EpoCanvas Docs는 EpoCanvas 오픈소스 생태계를 위해 만들어진 공식 기술 문서 사이트 시스템입니다. 현대적인 정적 웹사이트 프레임워크인 Astro 5와 Starlight를 기반으로 구축되었으며, 조판이 전문적이고 열리는 속도가 빠르며 검색이 편리하고 유지 관리가 쉬운 문서 플랫폼을 개발자에게 제공하는 것이 목표입니다.

제품 사용 설명서, API 인터페이스 규격, 시스템 아키텍처 설계 기록 등 어떤 문서를 쓰든, EpoCanvas Docs를 사용하면 작성자는 Markdown 콘텐츠 작성에 집중할 수 있고, 읽는 사람에게는 편안하고 자연스러운 읽기 경험을 제공할 수 있습니다.

해결하는 실제 문제

일상적인 개발과 기술 문서 작성에서 많은 팀이 문서를 유지 관리할 때 다음과 같은 어려움을 겪습니다:

페이지가 느리게 열리고 메모리를 많이 쓰는 문제: 많은 문서 도구가 생성하는 페이지에는 대량의 JavaScript 런타임이 포함되어 있어, 모바일이나 네트워크가 약한 환경에서는 열리는 속도가 느리고 긴 글을 스크롤할 때 버벅이기 쉽습니다.
긴 글 탐색이 힘든 문제: 흔한 문서 사이트는 보통 왼쪽 메뉴만 있어서, 수천 자에 달하는 긴 기술 설명을 읽을 때 현재 글 내부의 소제목 계층을 빠르게 파악하기 어렵습니다.
검색이 외부 서비스에 의존하는 문제: Algolia 같은 클라우드 검색 서비스는 별도로 계정을 신청하고 크롤러 키를 설정해야 하며, 외부 서비스에 접근할 수 없는 인트라넷 환경에서는 전혀 동작하지 않습니다.
다국어 지원이 절반만 되는 문제: 다국어를 지원한다고 주장하는 문서 사이트 중 상당수는 실제로는 내비게이션 버튼만 번역되어 있고, 글 본문에 들어가면 원문 그대로입니다. 번역이 누락되었을 때 바로 404가 뜨는 사이트도 있어, 독자가 직접 URL을 수정해가며 내용을 찾아야 합니다.

EpoCanvas Docs는 바로 이런 실제 문제를 해결하기 위해 설계되었습니다.

핵심 기능 한눈에 보기

브라우저에서 렌더링된 EpoCanvas Docs 제품 소개 페이지의 실제 모습: 왼쪽 카테고리 목차, 가운데 본문, 오른쪽 현재 페이지 목차

그림: 제품 소개 페이지의 실제 렌더링 결과. 왼쪽은 문서 카테고리 목차, 가운데는 본문, 오른쪽은 자동 생성된 “이 페이지의 목차” 개요로, 스크롤에 따라 현재 소제목이 하이라이트됩니다.

1. 명확한 3열 읽기 화면

왼쪽 내비게이션 바: 모든 문서 카테고리를 모듈별로 정리하고 계층 접기를 지원하며, 페이지를 이동해도 화면이 흔들리지 않습니다.
가운데 본문 영역: 본문 최대 너비는 60rem, 줄 간격은 1.68이며 코드 블록은 너비에 맞춰 조정되어, 오래 읽어도 피로하지 않습니다.
오른쪽 개요 바: 글 안의 h2와 h3 제목을 자동으로 가져와 “이 페이지의 목차”를 만들고, 스크롤에 따라 현재 읽고 있는 위치를 하이라이트하며, 소제목을 클릭하면 부드럽게 이동합니다.

2. 듀얼 모드 검색: 페이지 내 찾기 + 사이트 전체 검색

현재 페이지 찾기: 상단 검색창에 키워드를 입력하면 페이지 안의 일치하는 모든 텍스트가 즉시 하이라이트되고, 3/9 같은 진행 카운트가 표시되며, Enter를 누를 때마다 하나씩 이동합니다.
사이트 전체 검색 팝업: Ctrl + K(Mac은 Cmd + K)를 누르면 전역 검색 팝업이 열리고, Pagefind 정적 인덱스를 기반으로 일치하는 모든 문서와 단락 미리보기를 보여 줍니다.
모든 검색 기능은 브라우저 로컬에서 처리되며 백엔드 서비스에 의존하지 않으므로, 인트라넷에 호스팅해도 사용할 수 있습니다.

3. 10개 언어의 완전한 번역

간체 중국어, 번체 중국어, 영어, 일본어, 한국어, 스페인어, 프랑스어, 독일어, 러시아어, 포르투갈어 총 10개 언어를 지원하며, 각 언어의 내비게이션, 사이드바, 모든 문서 본문이 완전히 번역되어 있습니다.
오른쪽 위의 언어 버튼을 클릭하면 같은 글의 해당 언어 버전으로 이동하며, URL에 언어 접두사(예: /en/canvas/)가 붙어 즐겨찾기에 추가하거나 다른 언어를 쓰는 동료에게 바로 공유할 수 있습니다.
특정 페이지에 아직 해당 언어 번역이 없을 경우, 그 페이지는 자동으로 폴백되어 기본 중국어 콘텐츠를 표시하며 404 오류가 발생하지 않습니다.

4. 전문적인 Markdown과 코드 조판

Expressive Code 기반의 코드 하이라이트로, 코드 블록에 파일 이름 제목을 붙이거나 지정한 줄을 하이라이트하거나 diff 비교를 표시할 수 있습니다.
4가지 색상 콜아웃(Note, Tip, Caution, Danger)을 기본 지원하며, 제목을 직접 정할 수도 있습니다.
GFM 표, 작업 목록, 취소선 등 자주 쓰는 Markdown 확장 문법을 지원하며, 전체 규칙은 렌더링 규칙 상세를 참고하세요.

5. 빠른 빌드, 무료 호스팅

Astro 5 정적 컴파일을 기반으로 하며, 빌드 결과물은 순수 HTML, CSS와 필요할 때만 불러오는 소량의 JS로 구성됩니다. 10개 언어 약 180개 페이지 전체를 빌드하는 데 약 25초가 걸립니다.
Cloudflare Pages 배포 명령어가 미리 준비되어 있어, 한 줄 명령어로 문서를 온라인에 게시하고 HTTPS 인증서도 자동으로 받을 수 있습니다.

프로젝트 전체 아키텍처

문서를 가볍고 관리하기 좋은 상태로 유지하기 위해, 시스템은 역할에 따라 네 부분으로 나뉩니다:

EpoCanvas Docs 시스템 아키텍처 다이어그램: Markdown 콘텐츠 소스를 Astro가 컴파일하고 커스텀 UI 컴포넌트를 적용한 뒤, 최종적으로 정적 페이지를 생성해 Cloudflare Pages에 호스팅

그림: 시스템 아키텍처. 작성자는 Markdown 콘텐츠 소스만 관리하면 되고, 나머지 단계는 모두 자동으로 처리됩니다.

기반과 스타일: Astro 5 정적 커널을 기반으로 하며, src/styles/custom.css에서 디자인 변수를 정의합니다. 라이트 모드와 다크 모드가 같은 변수 이름을 공유합니다.
콘텐츠 소스 관리: 모든 문서는 src/content/docs/ 디렉터리에 저장되며, 순수 Markdown(.md) 또는 컴포넌트를 삽입할 수 있는 MDX(.mdx)로 작성합니다.
UI 컴포넌트: Starlight 기본 컴포넌트를 오버라이드하여 상단 바, 사이드바, 이 페이지의 목차, 검색 팝업을 커스터마이징했습니다.
배포와 접근: 컴파일 결과물은 dist/ 디렉터리에 저장되어 Cloudflare Pages에 호스팅되며, 전 세계 CDN 노드가 가까운 위치에서 응답합니다.

누구에게 적합한가

EpoCanvas Docs는 다음과 같은 상황에 적합합니다:

오픈소스 프로젝트의 공식 문서 사이트: 제품 설명서, API 참조, 아키텍처 설명을 저장소 하나로 모두 해결합니다.
팀 내부 지식 베이스: 순수 정적이고 외부 서비스 의존이 없어, 인트라넷에 두어도 검색 기능을 온전히 사용할 수 있습니다.
개인 기술 블로그식 문서: Markdown만 작성하면 되고 프런트엔드 엔지니어링을 신경 쓸 필요 없이 명령어 한 줄로 게시합니다.

반면 로그인 인증, 댓글 상호작용, 실시간 데이터 표시가 필요한 상황에는 적합하지 않습니다. 순수 정적 사이트에는 백엔드가 없으므로, 이런 요구 사항은 별도의 서비스를 함께 구성해야 합니다.

주요 문서 도구 비교

기능 특성	EpoCanvas Docs	Docusaurus	VitePress	GitBook 상업용
기반 기술	Astro 5 + Starlight	React 18	Vue 3 + Vite	클로즈드 소스 SaaS 플랫폼
검색 방식	Pagefind 로컬 정적 인덱스	Algolia 클라우드 서비스 의존	Minisearch 메모리 검색	자체 백엔드 검색
레이아웃 설계	3열(왼쪽 메뉴 + 가운데 본문 + 오른쪽 목차)	플러그인 설정으로 변경 필요	기본 2열/3열	고정 2열
배포 방식	Cloudflare Pages 직접 업로드	S3 / Vercel / GitHub	GitHub Pages	플랫폼 전용 호스팅
자체 관리 가능성	100% 오픈소스, 소스 코드를 완전히 보유	100% 오픈소스	100% 오픈소스	클로즈드 소스, 유료 기능이 많음

기술 스택과 버전

현재 버전에서 실제 사용하는 기술 스택입니다(빌드 결과물 기준):

구성 요소	버전	역할
Astro	v5.18.2	정적 사이트 커널, 빌드와 라우팅 담당
Starlight	v0.32.6	문서 사이트 프레임워크, 레이아웃 뼈대와 콘텐츠 처리 제공
Expressive Code	Starlight와 함께 통합	코드 블록 하이라이트, 제목 표시줄, 줄 하이라이트
Pagefind	`@pagefind/default-ui` 1.5.2로 통합	빌드 시점에 정적 검색 인덱스 생성
Wrangler	v4.131.0	Cloudflare 공식 CLI, 배포 실행
실행 환경	Node.js 18.20.8 / 20.3+ / 22+, pnpm 10	로컬 개발과 빌드 환경. `pnpm run deploy`는 wrangler 때문에 Node.js 22 이상이 필요합니다

의존성을 업그레이드할 때는 UI 컴포넌트와 커스텀 개발의 회귀 테스트 주의 사항도 함께 읽어 주세요.

프로젝트 디렉터리 구조

이 프로젝트의 코드 구성은 다음과 같으며, 각 디렉터리의 역할이 명확히 나뉘어 있습니다:

epocanvas-docs/
├── public/                    # 정적 자원 디렉터리 (이미지, 벡터 아이콘을 여기에 둔다)
│   └── images/canvas/         # UI 스크린샷과 시스템 아키텍처 벡터 다이어그램
├── src/
│   ├── components/starlight/  # 커스텀 페이지 컴포넌트 (상단 바, 사이드바, 이 페이지의 목차, 검색 팝업 등)
│   ├── config/navigation.ts   # 상단 내비게이션 바 설정 (메뉴 항목을 추가·삭제할 때 이 파일을 수정)
│   ├── content/docs/          # 문서 본문 Markdown 파일 위치
│   │   ├── index.mdx          # 문서 사이트 랜딩 페이지
│   │   ├── canvas/            # 각 장의 문서 (간체 중국어, 기본 언어)
│   │   └── en/ ja/ ...        # 나머지 9개 언어의 완전한 번역 디렉터리
│   ├── styles/custom.css      # 전역 스타일과 테마 색상 변수
│   ├── utils/i18n.ts          # UI 문구 사전과 언어 목록
│   └── pages/404.astro        # 직접 만든 404 페이지(브라우저 언어로 안내 문구 출력)
├── scripts/                   # 빌드 전 캐시 무효화, i18n·이미지·앵커 점검, 스크린샷 생성 스크립트
├── astro.config.mjs           # 사이트 메인 설정 파일 (제목, 언어 목록, 사이드바 목차를 여기서 설정)
└── package.json               # 프로젝트 의존성과 실행 명령어 설정

다음 단계

프로젝트를 로컬에서 실행해 보고 싶다면 **빠른 시작 (3분 만에 실행)**을 읽어 주세요.
화면의 구체적인 레이아웃과 사용 방법이 궁금하다면 **페이지 레이아웃과 읽기 경험**을 읽어 주세요.
새 문서를 작성하기 시작하려면 **Markdown 작성 및 서식 가이드**와 **렌더링 규칙 상세**를 읽어 주세요.