AI 에이전트와 개발자가 웹사이트, 문서 또는 블로그를 배포할 수 있도록 구축된 오픈 소스 (open-source) 퍼블리싱 프레임워크입니다. 마크다운 (markdown)을 작성하고 터미널에서 동기화하세요. 당신의 콘텐츠는 브라우저, LLM, 그리고 AI 에이전트에서 즉시 확인할 수 있습니다. Convex를 기반으로 구축되었습니다.

로컬에서 마크다운을 작성하고, npm run sync를 실행하여

(개발 (dev)) 또는 npm run sync:prod를 실행하여

(운영 (production)) 환경을 구축하면, 모든 연결된 브라우저에 콘텐츠가 즉시 나타납니다. React, Convex, Vite로 구축되었습니다. AEO, GEO 및 LLM 발견 (discovery)에 최적화되어 있습니다.

퍼블리싱 작동 방식: 마크다운으로 포스트를 작성하고, 개발용으로는 npm run sync를, 운영용으로는 npm run sync:prod를 실행하면 라이브 사이트에 즉시 나타납니다. 재빌드 (rebuild)나 재배포 (redeploy)가 필요하지 않습니다. Convex가 실시간 데이터 동기화 (real-time data sync)를 처리하므로, 모든 연결된 브라우저가 자동으로 업데이트됩니다.

동기화 명령 (Sync commands):

동기화 명령 스크립트는 scripts/에 위치합니다 (sync-posts.ts, sync-discovery-files.ts).

개발 (Development):

npm run sync

• 마크다운 콘텐츠 동기화

npm run sync:discovery

• AGENTS.md, CLAUDE.md, llms.txt 업데이트 (위키 페이지 포함, AGENTS.md를 public/로 복사)

npm run sync:wiki

• content/blog 및 content/pages에서 위키 동기화

npm run sync:all

• 콘텐츠 + 위키 + 발견 (discovery) 파일을 함께 동기화

운영 (Production):

npm run sync:prod

• 마크다운 콘텐츠 동기화

npm run sync:discovery:prod

• 발견 (discovery) 파일 업데이트

npm run sync:wiki:prod

• 운영 환경으로 위키 동기화

npm run sync:all:prod

• 콘텐츠 + 위키 + 발견 (discovery) 파일을 함께 동기화

지식 베이스 (Knowledge base) 동기화:

npm run sync:wiki -- --kb=<id>

• 특정 지식 베이스 (knowledge base)로 위키 동기화

대시보드 콘텐츠 내보내기 (Export dashboard content):

npm run export:db

• 대시보드 포스트/페이지를 콘텐츠 폴더로 내보내기 (개발 (development))

npm run export:db:prod

• 대시보드 포스트/페이지 내보내기 (운영 (production))

버전 관리 (Versioning) 작동 방식: 마크다운 파일은 content/blog/ 및 content/pages/에 존재합니다. 이 파일들은 당신의 git 리포지토리 (git repo)에 있는 일반 파일입니다. 변경 사항을 커밋 (commit)하고, 차이점 (diffs)을 검토하며, 다른 코드베이스와 마찬가지로 롤백 (roll back)할 수 있습니다. 동기화 명령이 콘텐츠를 Convex로 푸시 (push)합니다.

수정, 커밋, 동기화

git add content/blog/my-post.md
git commit -m "Update post"
...

전체 문서는 markdown.fast/docs에서 확인할 수 있습니다.

• 설정 가이드 (Setup Guide) - 전체 포크 (fork) 및 배포 가이드

• 포크 설정 가이드 (Fork Configuration Guide) - 자동 또는 수동 포크 설정

• 대시보드 가이드 (Dashboard Guide) - 콘텐츠 관리 및 사이트 설정

• MCP 서버 (MCP Server) - Cursor 및 Claude Desktop을 위한 AI 도구 통합

• WorkOS 설정 (WorkOS Setup) - 레거시 인증 모드 (siteConfig에서 auth.mode: "workos" 사용)

이 프로젝트에는 AI 코딩 어시스턴트 (AI coding assistants)에 최적화된 문서가 포함되어 있습니다:

CLAUDE.md - 워크플로 (workflows), 명령 (commands) 및 컨벤션 (conventions)이 포함된 Claude Code CLI용 프로젝트 지침
AGENTS.md - 코드베이스 구조 이해를 위한 일반적인 AI 에이전트 (AI agent) 지침
llms.txt - /llms.txt에 위치한 AI 에이전트 발견 (discovery) 파일

.cursor/skills/ - 특정 기술 문서:
frontmatter.md - 완전한 프론트매터 (frontmatter) 구문 및 모든 필드 옵션
convex.md - 이 앱에 특화된 Convex 패턴
sync.md - 동기화 명령 작동 방식 및 콘텐츠 흐름
robel-auth/SKILL.md - @robelest/convex-auth 통합 패턴
convex-self-hosting/SKILL.md - Convex 정적 셀프 호스팅 (static self hosting) 설정

이 파일들은 npm run sync:discovery 실행 시 현재 사이트 통계와 함께 자동으로 업데이트됩니다.

AI 에이전트 통합 (AI agent integration) - API 엔드포인트 (endpoints), 원본 마크다운 (markdown) 파일, skills.md 및 MCP 서버가 포함됩니다.

파일 기반 퍼블리싱 (File-based publishing) - 마크다운을 로컬에 작성하면 버전 관리 (version control)와 함께 모든 곳으로 콘텐츠가 동기화됩니다.

LLM 위키 및 지식 베이스 (LLM wiki and knowledge bases) - 콘텐츠를 기반으로 검색 가능한 위키를 구축합니다. Obsidian 보관함 (vaults) 또는 마크다운 폴더를 지식 베이스 프로젝트로 업로드하여 지식 베이스(KB)별 API 액세스를 사용할 수 있습니다.

지식 그래프 (Knowledge graph) - 위키 페이지와 지식 베이스가 어떻게 연결되는지에 대한 대화형 시각화.

가상 파일 시스템 (Virtual filesystem) - /vfs/exec를 통해 모든 사이트 콘텐츠에 대해 ls, cat, grep, tree를 사용할 수 있는 셸 (shell) 스타일의 HTTP 인터페이스. 인증이 필요하지 않습니다.

URL 콘텐츠 가져오기 (URL content import) - Firecrawl을 사용하여 모든 웹페이지를 마크다운으로 가져오고 스크래핑 (scrape)합니다.

다양한 출력 형식 (Multiple output formats) - API 엔드포인트를 통한 JSON, 가공되지 않은 .md 파일, 그리고 RSS 피드를 지원합니다.

실시간 팀 동기화 (Real-time team sync) - 여러 개발자가 서로 다른 기기에서 npm run sync를 실행할 수 있습니다. 연결된 모든 브라우저가 즉시 업데이트됩니다.

동기화 명령 (Sync commands) - 단 하나의 명령으로 콘텐츠, 위키(wiki), 디스커버리(discovery) 파일을 동기화합니다. AGENTS.md, CLAUDE.md, llms.txt를 자동으로 업데이트합니다.

시맨틱 검색 (Semantic search) - OpenAI 임베딩 (embeddings)을 사용하여 단순 키워드가 아닌 의미를 통해 콘텐츠를 찾습니다.

AI에게 질문하기 (Ask AI) - 사이트 콘텐츠와 채팅하세요. Cmd+J를 통해 출처와 함께 답변을 얻을 수 있습니다.

관리자 대시보드 (Admin dashboard) - 실시간 미리보기, 분석 (analytics), 설정 편집기, 동기화 버튼, 지식 베이스 (knowledge base) 관리를 포함한 완전한 콘텐츠 관리 기능을 제공합니다.

익명 데모 모드 (Anonymous demo mode) - 방문자는 로그인 없이 대시보드를 탐색할 수 있습니다. 데모 콘텐츠는 30분마다 초기화됩니다.

네 가지 테마 (Four themes) - 다크 (Dark), 라이트 (Light), 탄 (Tan), 클라우드 (Cloud) 테마와 폰트 전환기 (serif, sans, monospace)를 제공합니다.

전체 텍스트 검색 (Full text search) - Command+K 단축키를 통해 포스트, 페이지, 위키 전반에 걸쳐 결과 하이라이팅과 함께 검색할 수 있습니다.

전체 기능 목록은 About 페이지에서 확인하세요.

포크 (forking) 후, 자동 구성 명령을 실행하세요:

cp fork-config.json.example fork-config.json
# fork-config.json을 사이트 정보로 편집하세요
npm run configure

fork-config.json.example에는 모든 설정 가능한 옵션이 포함되어 있습니다:

사이트 설정 (Site settings): 이름 (name), 제목 (title), 설명 (description), URL, 도메인 (domain)
인증 모드 (Auth mode): convex-auth (기본값), workos (레거시), 또는 none (로컬 개발)
호스팅 모드 (Hosting mode): convex-self-hosted (기본값) 또는 netlify (레거시)
미디어 제공자 (Media provider): convex (기본값), convexfs, 또는 r2

자세한 지침은 Fork Configuration Guide를, 전체 참조를 보려면 FORK_CONFIG.md를 참조하세요.

자신만의 클론과 Convex 백엔드를 빠르게 구축하려면 다음 중 하나의 경로를 사용하세요:

• GitHub 템플릿 흐름:

  • Use this template 클릭
  • 생성된 새 리포지토리(repo)를 클론 (Clone)
  • npm install, npx convex dev --once, npm run sync, npm run deploy 실행

• CLI 흐름:

  • npx create-markdown-sync my-site 실행
  • 프롬프트에 따라 진행하고 설정이 완료되면 사이트를 엽니다.

• 웹사이트 설정 가이드:

• Node.js 18 이상

• Convex 계정

• 의존성 설치 (Install dependencies):

npm install

• Convex 초기화 (Initialize Convex):

npx convex dev

이 명령은 Convex 프로젝트를 생성하고 .env.local 파일을 생성합니다.

WSL 2를 사용 중이고 브라우저 인증이 열리지 않는 경우, 다음을 실행하세요:

npx convex login --no-open --login-flow paste
npx convex dev --once

그 다음 일반적인 watch 모드를 시작합니다:

npx convex dev

• 개발 서버 시작 (Start the development server):

npm run dev

환경 및 배포 확인 (Verify your environment and deployment):

npm run validate:env # 로컬 환경 준비 상태 확인
npm run validate:env:prod # 프로덕션 환경 확인
npm run verify:deploy # 배포된 엔드포인트 검증
...

npx @convex-dev/self-hosting setup
npx convex dev --once
npm run deploy

npm run deploy는 @convex-dev/self-hosting을 통해 전체 원샷 (one-shot) 흐름을 실행하며, 대상 Convex 배포를 위해 자동으로 빌드합니다.

• Convex 대시보드에서 Convex 커스텀 도메인을 markdown.fast로 설정하세요.

• Convex에서 제공하는 레코드를 사용하여 Cloudflare의 DNS를 Convex로 지정하세요.

• 프론트엔드 HTTP 라우트 오버라이드 (overrides)를 위해 VITE_CONVEX_SITE_URL (또는 VITE_SITE_URL)을 설정하세요.

• Convex 클라이언트 URL을 위해 VITE_CONVEX_URL을 유지하세요.

• Convex 함수를 프로덕션에 배포 (Deploy Convex functions to production):

npx convex deploy

• 저장소를 Netlify에 연결하세요.

• 빌드 설정 구성 (Configure build settings):

• 빌드 명령 (Build command):
  npm ci --include=dev && npx convex deploy --cmd 'npm run build'

• 게시 디렉토리 (Publish directory):
  dist

• 빌드 명령:

• Netlify 대시보드에서 환경 변수 추가:
  CONVEX_DEPLOY_KEY

• Convex Dashboard > Project Settings > Deploy Key에서 생성하세요.
  VITE_CONVEX_URL

• 귀하의 프로덕션 Convex URL

자세한 설정은 Convex Netlify 배포 가이드(Convex Netlify Deployment Guide)와 문제 해결을 위한 netlify-deploy-fix.md를 참조하세요.

기본 모드 (Default mode):

auth.mode: "convex-auth"

• @robelest/convex-auth를 통한 GitHub OAuth

hosting.mode: "convex-self-hosted"

• @convex-dev/self-hosting을 통한 정적 자산 (Static assets)

media.provider: "convex"

• 직접적인 Convex 스토리지

레거시 모드 (Legacy mode):

`auth.mode: "workos""

WorkOS AuthKit 호환성을 위한 auth.mode: "workos"

hosting.mode: "netlify"

Netlify 배포를 위한 media.provider: "convexfs"

또는 media.provider: "r2"

선택적 미디어 백엔드(media backends)를 위한 설정

로컬 폴백 모드 (Local fallback mode):

auth.mode: "none"

로컬 개발 전용

dashboard.requireAuth: true인 경우 대시보드 접근은 서버에서 강제됩니다.

.

• GitHub Developer Settings로 이동
• 새로운 OAuth App 생성
• Homepage URL을 프론트엔드 URL로 설정 (예: http://localhost:5173)
• Authorization callback URL을 다음과 같이 설정: https://<your-deployment>.convex.site/api/auth/callback/github
• Client ID와 Client Secret 복사

npx convex env set AUTH_GITHUB_ID "your-github-client-id"
npx convex env set AUTH_GITHUB_SECRET "your-github-client-secret"
npx convex env set DASHBOARD_ADMIN_BOOTSTRAP_KEY "choose-a-long-random-secret"

npx convex run authAdmin:bootstrapDashboardAdmin \ 
'{"bootstrapKey":"choose-a-long-random-secret","email":"your-email@example.com"}'

npx convex run authAdmin:grantDashboardAdmin '{"email":"colleague@example.com"}'

npx convex env set DASHBOARD_PRIMARY_ADMIN_EMAIL "your-email@example.com"

전체 관리자 설정 지침은 FORK_CONFIG.md를 참조하세요.

React 18, TypeScript, Vite, Convex (self hosted), @robelest/convex-auth, @convex-dev/self-hosting.

레거시 모드 (Legacy mode): Netlify + WorkOS.

애플리케이션 레벨 속도 제한 (Application-level rate limiting): @convex-dev/rate-limiter를 사용하여 모든 공개 엔드포인트에 대해 4단계 보호(LLM 비용, 헤비 리드 (heavy reads), 공개 뮤테이션 (public mutations), 표준 리드 (standard reads))를 적용합니다.

LLM 위키 (LLM wiki): GPT-4o mini가 사이트 콘텐츠를 바탕으로 백링크, 카테고리 및 지식 그래프 (knowledge graph)와 함께 컴파일합니다.

지식 베이스 (Knowledge bases): Obsidian 볼트(vaults) 또는 마크다운 폴더를 업로드할 수 있으며, 지식 베이스(KB)별 API 접근 및 가시성 제어를 제공합니다.

가상 파일 시스템 (Virtual filesystem): /vfs/tree 및 /vfs/exec에서 인증되지 않은 셸(shell) 스타일의 모든 콘텐츠 접근을 지원합니다.

익명 데모 모드 (Anonymous demo mode): /dashboard에서 제공되며 30분 후 자동 정리됩니다.

위키 동기화 명령 (Wiki sync commands): (npm run sync:wiki, npm run sync:all)

) CLI 기반 위키 생성용

Convex 셀프 호스팅 (Convex self hosting): @convex-dev/self-hosting을 통한 기본 배포

@robelest/convex-auth: GitHub OAuth를 이용한 기본 인증

convex-doctor 점수: 100/100: 보안, 성능, 정확성, 스키마 (Schema), 아키텍처 (Architecture) 전반에 걸쳐 달성

전체 버전 기록은 변경 이력 (Changelog)을 확인하세요.

이 프로젝트를 포크(Fork)하세요: github.com/waynesutton/markdown-site

이 프로젝트는 MIT 라이선스 (MIT License)를 따릅니다.