for humanity
| 항목 | 내용 |
|---|---|
| 기간 | 2026.09 ~ 현재 |
| 역할 | 단독 설계, 구현, 문서, 배포 |
| 개요 | Markdown 문서를 공개와 내부로 나눠 정적 사이트로 만드는 CLI입니다. npm 패키지 for-humanity로 배포하고 이 사이트도 이 도구로 만들었습니다. 2026.10.03 첫 배포 뒤 2026.10.22의 0.18.0까지 30개 버전을 냈습니다. |
| 링크 | for-humanity.fyi, GitHub, npm |
| 기술 | TypeScript, Hono, Vite 8, unified(remark, rehype), Shiki, Mermaid 12, Zustand, Zod, Citty, Vitest, Playwright, Biome, GitHub Actions, Cloudflare Pages |
주요 업무
문서 수집과 공개 범위
public 폴더는 배포하고 private 폴더는 로컬에서만 읽도록 수집 규칙을 나눴습니다. 홈이나 공개 문서가 내부 문서, 이미지, 스니펫을 참조하면 파일과 줄 번호를 보여 주고 빌드를 멈춥니다. 설정은 프로젝트 루트의 for-humanity.config.ts 하나이며 SiteConfig 타입으로 검사합니다.
렌더링과 서버
페이지는 Hono JSX로 서버에서 그리고 탐색과 목차 같은 상호작용만 브라우저 스크립트로 둡니다. dev 서버와 정적 빌드는 같은 문서 준비 단계와 라우트를 공유하고 Vite 하나로 HMR과 preview를 처리합니다. 처음에는 React 서버 렌더러였고 0.5.0에서 Hono JSX로 바꿨습니다.
문서 기능
중첩 그룹과 부모 문서로 탐색을 구성하고 part, note, details로 절을 묶습니다. 코드 블록은 Shiki 강조와 줄 표기를 지원하고 별도 파일의 region을 스니펫으로 가져옵니다. Mermaid 12를 로컬에서 불러 다이어그램을 그리고 이미지, 영상, 소리, 첨부는 참조한 파일만 fingerprint URL로 복사합니다. 상태 표지, 사이트맵, canonical과 Open Graph 태그, basePath를 설정으로 켭니다.
입력 검증
잘못된 part 제목, 닫히지 않은 스니펫 region, 이미지가 아닌 파일 참조, 없는 미디어 파일은 파일과 줄 번호를 표시하고 빌드를 실패시킵니다. 없는 문서 링크는 경고만 하고 계속 진행합니다. 0.15.0에서 이전 버전이 받아들이던 입력을 오류로 바꿨습니다.
검증과 배포
명령, 문서, 페이지, 서버 네 영역의 시나리오를 Vitest와 Playwright로 검증하고 Biome, Stylelint, TypeScript, knip을 CI에서 돌립니다. 버전 태그를 올리면 GitHub Actions가 npm Trusted Publishing으로 배포하고 GitHub Release를 만듭니다. 문서 사이트는 Cloudflare Pages에 배포합니다.
시작 도구
init 명령이 사이트 이름, 문서 폴더, 언어, 호스팅을 대화형으로 묻고 설정, 첫 문서, 실행 스크립트, GitHub Pages나 Cloudflare Pages 배포 파일을 만듭니다. 기존 스크립트와 의존성은 유지하고 충돌하면 파일을 만들기 전에 멈춥니다.