본문으로 건너뛰기
REPL WorksREPL Works
Menu

SHOWCASE SPECIFICATION

ManualPress

Git 저장소의 마크다운 문서를 바로 웹사이트로 발행하는 문서 플랫폼입니다.

1. 개요 (Overview)

ManualPress 홈페이지

ManualPress는 GitHub 문서 저장소의 Markdown 파일을 정적 문서 사이트로 발행하는 웹 서비스입니다. Hub에서 작성자는 공개 저장소와 게시할 브랜치를 등록하고, Hub 경로·커스텀 도메인·GitHub Pages 중 배포 대상을 선택합니다. 독자는 문서를 탐색하고, 버전을 바꾸고, 검색할 수 있습니다.

"문서 저장소는 Markdown으로 유지하고, 게시와 사이트 생성을 서비스가 맡습니다."

GitHub에 변경 사항을 push하면 게시된 사이트를 다시 빌드할 수 있으며, Hub에서 수동으로 빌드할 수도 있습니다. 문서 저장소에는 front matter, 컴포넌트, 빌드 설정을 둘 필요가 없습니다.

2. 사용된 표준 문서 (Documents Used)

ManualPress 저장소는 공통 규칙과 REPL Works 표준 문서로 제품 정의, 구현 제약, 아키텍처, 작업 순서를 관리합니다.

  • AGENTS.md: 에이전트가 따라야 할 문서 순서와 작업 규칙
  • .replworks/PRODUCT_SPEC.md: Hub와 Site의 제품 요구사항
  • .replworks/TECH_STACK.md: 기술 스택과 구현 제약
  • .replworks/ARCHITECTURE.md: 구성 요소와 데이터 흐름
  • .replworks/TASKS.md: 구현할 작업과 수용 기준

3. 적용 워크플로 (Workflow Usage)

대화형 AI (문서 발행 서비스의 요구사항과 정책 정의)
↓
REPL Works 문서 (제품, 기술, 아키텍처, 작업 계획)
↓
코딩형 AI (TASKS.md의 작업 단위로 구현하고 검증)
↓
Human Review (PR과 CI 결과를 확인하고 Release)

공통 규칙은 구현 전에 제품·기술·아키텍처 문서와 작업 정의를 읽도록 합니다. 코딩형 AI는 선택된 작업만 구현하고, 내부 로직 테스트와 외부 경계 검증을 수행한 뒤 완료된 작업을 기록합니다. 변경은 PR과 CI를 통해 검토하고, Release를 발행해 운영에 반영합니다.

4. 사용 기술 (Tools Used)

  • PHP 8.4, Laravel 13, Livewire 4: 작성자가 문서 저장소와 게시 설정을 관리하는 Hub
  • CommonMark, Phiki: Markdown 문서 변환과 코드 구문 강조
  • MySQL, Redis: 프로젝트 설정, 문서 스냅샷, 캐시와 작업 큐
  • Docker: 저장소 빌드 격리
  • Cloudflare R2, Workers: 정적 Site 파일 저장과 Reader 요청 처리
  • Node.js, Vite, Tailwind CSS: Hub 프론트엔드 자산 빌드
  • GitHub Actions, Coolify, GHCR: 검증, 이미지 빌드, 애플리케이션 배포

5. 배포와 운영 (Release & Operations)

ManualPress는 https://manualpress.net에서 Hub를 제공하고, 게시된 문서는 Site 도메인과 각 배포 대상에서 정적 파일로 제공합니다. Hub와 Reader가 이용하는 Site를 분리해, 문서 읽기 요청은 Site 경로에서 처리합니다.

작성자는 GitHub push 또는 Hub의 수동 빌드로 Site를 갱신합니다. Release를 게시하면 CI가 통과한 뒤 새 애플리케이션 이미지를 만들고 운영 환경에 배포합니다.

6. 학습된 레슨 (Lessons Learned)

문서 작성에 빌드 설정을 요구하지 않으려면 게시 파이프라인을 문서 저장소와 분리해야 합니다. ManualPress는 서비스가 사이트 생성을 맡아 작성자가 평범한 Markdown 파일을 편집하고 GitHub에 push하는 흐름을 유지합니다.