Architecture
라이브러리 내부 구현을 수정하는 사람을 위한 참고 문서. Hono 라우팅과 정적 출력, React 서버 렌더링, unified Markdown processor. 브라우저 동작은 작은 DOM 스크립트 하나.
Overview
| Entry | Responsibility | Runtime |
|---|---|---|
cli.ts | 인자 · 설정 · 문서 · 폰트 · 빌드·서버 시작 | Node.js |
app.tsx | 첫 화면과 문서 라우트 · React → HTML | Node.js |
dev.ts | 자원 · SSE 새로고침 · 페이지 앱 위임 | Node.js · dev |
client.ts | 커서 장식 · 읽는 section · 접힌 hash 보정 | Browser |
Routing and rendering
페이지 앱의 라우트: /, /:slug{.+}/. 문서 id에는 하위 폴더 포함.
/는 문서 폴더의 README.md. 일반 문서 목록과 별도로 읽고, 개발 중 함께 갱신.
- React:
renderToStaticMarkup으로 HTML 문서 생성 - build: Hono
ssgParams와toSSG로 같은 라우트 출력 - dev:
@hono/node-server로 같은 페이지 앱 제공 - preview:
serveStatic으로 빌드 결과 제공
페이지 앱과 dev 앱의 분리는 SSG 대상과 개발 전용 자원의 경계. Hono 정규식 매개변수와 wildcard 라우트 혼합 시 Router 제약도 이 경계에서 격리.
Design choices
문서 사이트에는 hydration과 React 브라우저 번들 불필요.
서버 TSX는 페이지 조립, DOM 스크립트는 작은 상호작용 담당.
@hono/react-renderer는 렌더링 middleware가 필요할 때의 선택지.
현재 공통 HTML 틀은 WgShell 소유 · 직접 React 렌더링 유지.
참조: Hono SSG, Node.js Adapter, React static rendering.
Markdown pipeline
| Stage | Work |
|---|---|
| Read | 파일 탐색 · remark-frontmatter의 YAML 노드 · yaml 값 해석 · Zod 검증 |
| remark | GFM · 문장부호 · Note·Details · part · 흐름도 · status badge · swatch · 링크 · 경고 |
| rehype | 코드 강조 · 문서 header · 제목 id · 가름 수집 · 표 상자 |
| Output | raw HTML 해석 · HTML 문자열 |
제목 원문에서 id와 TOC 텍스트를 수집하고 가름별로 묶음. 제목 번호는 자동 생성하지 않음.
중간 계약은 file.data.fh. 제목과 section 정보는 문서 순서 유지.
frontmatter는 정규식으로 잘라내지 않고 AST 노드로 읽음. 본문 노드의 원본 줄·열은 유지.
Note·Details의 검증은 Markdown 부품 변환 전. 제목은 native label, 본문은 기존 처리 흐름.
접힌 본문의 ###도 같은 제목 id·TOC. 부품의 작성 계약은 Parts.
remark는 Markdown을 AST로 다루는 플러그인 체계. 현재의 부품 변환·검증과 rehype 연결에 사용.
markdown-it도 확장 가능한 렌더러이며 VitePress에서 사용. 한쪽이 항상 더 좋은 것은 아니고, 이 프로젝트는 기존 AST 변환을 유지.
gray-matter는 frontmatter를 분리·해석하는 다른 선택지. 여기서는 remark-frontmatter와 기존 yaml을 조합.
참조: remark, remark-frontmatter, gray-matter, VitePress Markdown.
Code ownership
| Concern | Owner |
|---|---|
| 첫 화면 · 문서 페이지 | src/page |
| HTML 틀 · 사이드바 | src/component/widget/shell |
| 본문 · remark·rehype 플러그인 | src/component/widget/prose |
| processor · 문서 읽기 | src/content |
| 상수 · 문구 · 스키마 | src/constant · src/type |
| 색 · 폰트 · 간격 | src/style/token.css |
| 격자 렌더러 · 폰트 변환 | src/util |
Package output
build:kit: esbuild로 서버 CLI와 CSS, 브라우저 스크립트 생성.
폰트와 favicon 원본은 패키지에 포함, 사이트 빌드 시 결과 폴더로 복사.
dist/cli.js: npm bin 진입점dist/cli.css: 컴포넌트 CSS 묶음dist/client.js: 브라우저 스크립트- 자원 URL:
/_fh/· favicon:/favicon.svg
패키지 빌드와 문서 사이트 빌드는 별도 단계. 절차는 Maintenance.
