TL;DR

  • repoDocs는 저장소별 Markdown(.md) 문서 폴더를 읽어 검색·상태 필터·섹션 편집이 가능한 Figma 스타일 보드로 변환하고 변경 사항을 원본 파일에 다시 기록하는 도구임.
  • 긴 문서를 접을 수 있는 섹션별 카드로 표시하고, ✅ 완료 · 📌 대기 · 🔶 진행 중 상태를 프로젝트별로 설정해 필터링함.
  • 브라우저의 localStorage에 먼저 편집 내용을 저장하며, Vite 환경에서는 섹션 저장과 전체 문서 저장을 통해 실제 .md 파일에 변경 사항을 기록함.
  • 내보내기·복사 기능은 수정 사항을 반영한 전체 Markdown을 재생성하고, 초기화 기능은 파일을 건드리지 않고 로컬 편집 내용만 삭제함.
  • scripts/sync-docs.mjs가 Markdown을 섹션으로 분석하고 상태를 감지하며, 생성 파일은 비공개 문서가 커밋되지 않도록 gitignore 처리됨.

repoDocs

  • 저장소별 Markdown 문서가 들어 있는 폴더를 읽어 Figma 스타일 보드 또는 캔버스로 변환함.
  • 보드에서 문서를 읽고 검색하며 상태별로 필터링하고 모든 섹션을 편집할 수 있음.
  • 변경 사항을 실제 .md 파일에 직접 기록함.

사용 이유

  • AGENTS.md와 RECOMENDACIONES.md는 프로젝트의 단일 진실 공급원(single source of truth)이지만, 코딩 중인 저장소 내부에서 문서를 읽는 경험은 좋지 않음.
  • repoDocs는 .md 파일이 있는 모든 폴더를 읽고 최신 문서를 보드의 카드 또는 캔버스로 변환함.
  • 긴 문서를 별도의 접을 수 있는 섹션으로 읽을 수 있음.
  • 프로젝트별로 설정 가능한 상태인 ✅ 완료 · 📌 대기 · 🔶 진행 중으로 검색하고 필터링함.
  • 모든 섹션을 인라인으로 편집하고 실시간 Markdown 미리보기를 확인함.
  • 전체 Markdown을 내보내거나 원본 .md 파일에 다시 기록함.
  • 설정 기반으로 앱의 휴대전화 스타일 목업을 선택적으로 미리 볼 수 있음.

빠른 시작

  • 프로젝트 의존성을 설치하고 개발 서버를 실행하면 ./examples를 스캔한 뒤 http://localhost:5173에서 보드를 제공함.
  • examples/의 데모 문서는 별도 설정 없이 작동함.
  • 자체 저장소를 연결하려면 mdboard.json을 mdboard.local.json으로 복사한 뒤 로컬 설정을 편집함.
  • mdboard.local.json은 이미 Git에서 무시되도록 설정됨.
  • mdboard.json에는 공개 기본값을 저장하며 커밋 대상임.
  • 로컬 또는 비공개 설정은 이미 gitignore 처리된 mdboard.local.json에 저장함.

편집 워크플로

  • 편집 내용은 항상 먼저 브라우저의 localStorage에 저장되며 키는 pb:edits임.
  • Vite 서버의 개발 또는 미리보기 환경에서 제공할 경우 섹션 저장이 실제 .md 파일에 기록됨.
  • 기록은 POST /__mdboard/write 미들웨어를 통해 수행됨.
  • 상단 바의 💾 저장 버튼은 전체 문서를 기록함.
  • MDBOARD_NO_WRITE=1을 설정하거나 Vite 외부에서 실행하면 편집 내용이 로컬에만 남음.
  • 내보내기 또는 복사 기능은 변경 사항을 적용한 전체 Markdown을 재구성하며 수동 붙여넣기에 사용할 수 있음.
  • ↺ 초기화는 모든 로컬 편집 내용을 삭제하며 파일에는 절대 접근하지 않음.

스크립트

  • npm run sync: projectsRoot를 다시 스캔하고 src/generated/{docs,appconfig}.ts를 재생성함.
  • npm run dev: 먼저 동기화를 실행한 뒤 Vite 개발 서버를 실행함.
  • npm run build: 먼저 동기화를 실행한 뒤 tsc -b와 vite build를 실행함.
  • npm run lint: oxlint를 실행함.
  • npm run smoke: 자체 미리보기 서버를 :5199에서 실행하는 종단 간 스모크 테스트이며 쓰기 기능은 비활성화됨.

작동 방식

  • scripts/sync-docs.mjs는 각 .md 파일을 H1/H2 블록 기준으로 섹션화함.
  • 설정에 지정된 이모지와 요약 표를 기준으로 상태를 감지함.
  • 요약 표는 특수 요약 섹션으로 유지되며 내보내기 시 다시 생성되고 직접 편집되지는 않음.
  • 편집 내용은 src/lib/registry.ts의 assembleRaw()를 통해 줄 범위별로 저장함.
  • 이 방식은 구분자와 순서를 보존하며, 아무것도 편집하지 않은 경우 내보낸 Markdown이 바이트 단위로 동일하게 유지됨.
  • src/generated/는 자동 생성되며 Git에서 무시됨.
  • 따라서 비공개 문서가 커밋되는 일이 없음.

라이선스

  • MIT © 2026 Alejandro Guerrero 라이선스임.
  • 프로젝트 후원은 GitHub Sponsors를 통해 가능하며 관련 정보는 FUNDING.yml에 있음.