feat(web): render docs from repo-root docs/ as MDX SoT at build time

Replace the bespoke 16-section /docs page that pulled prose from
`messages/{locale}.json` with a build-time MDX renderer that reads the
canonical markdown in repo-root `docs/`. Each markdown file becomes
one section of the docs page, scrolled-to via the existing DocsShell
sidebar. Section data structure stays in `lib/docs-sections.ts` so the
sidebar / scroll-spy keeps working with no client changes.

Why this layout:

- One source of truth: `docs/guide/*.md`, `docs/reference/*.md`,
  `docs/manifesto.md`. Edits land in one place; the website redeploys
  pick them up automatically via the existing web-deploy workflow.
- Build-time only: `MDXRemote` is rendered inside an RSC and the page
  is statically generated (`●` SSG). Cloudflare Workers serves the
  rendered HTML; no MDX compiler runs at request time.
- next-intl unchanged for everything else: only the docs prose moves
  out. `mobileHeader` and `searchPlaceholder` strings stay in
  `messages/{locale}.json`; the 18 stale section keys are removed.

Files:

- web/lib/docs-sections.ts: 9 sections matching docs/ files, typed
  `DocSection` with `{ id, title, file }`.
- web/lib/docs-source.ts: `loadDocSource(file)` reads
  `<repo-root>/docs/<file>` at build time via `node:fs/promises`.
- web/components/docs/mdx-components.tsx: shadcn-styled overrides for
  every markdown element (h1-h4, p, a, ul/ol/li, blockquote, code, pre,
  table, hr, strong) so the rendered output matches the rest of the
  site.
- web/app/[locale]/docs/page.tsx: rewritten as an async RSC that loads
  every section's source in parallel and renders one MDXRemote per
  section inside DocsShell.
- web/messages/{en,ja,ko,zh}.json: `docs` key trimmed from 20 entries
  to 2 (mobileHeader, searchPlaceholder).
- web/package.json: + next-mdx-remote, + gray-matter.

Local verification: `bun run format:check`, `bun run lint`,
`bun run type-check`, `bun run build`, `bunx opennextjs-cloudflare
build` all pass; `/[locale]/docs` builds as static for all 4 locales
at 4.12 kB / 132 kB First Load.
This commit is contained in:
YeonGyu-Kim
2026-05-08 16:14:55 +09:00
parent 810e3c7a51
commit e5369f3a63
10 changed files with 441 additions and 1238 deletions
+1 -172
View File
@@ -247,178 +247,7 @@
},
"docs": {
"mobileHeader": "Oh My OpenAgent Docs",
"searchPlaceholder": "문서 검색...",
"sections": {
"overview": "Overview",
"quickStart": "Quick Start",
"configLocations": "Config File Locations",
"agents": "Agents",
"categories": "Categories",
"skills": "Skills",
"backgroundTasks": "Background Tasks",
"hooks": "Hooks",
"mcps": "MCPs",
"browserAutomation": "Browser Automation",
"tmux": "Tmux Integration",
"gitMaster": "Git Master",
"commentChecker": "Comment Checker",
"experimental": "Experimental Features",
"lsp": "LSP Configuration",
"envVars": "Environment Variables"
},
"overview": {
"title": "Configuration Reference",
"description": "Oh My OpenAgent는 강력한 의견을 가지고 있지만 취향에 맞게 조정할 수 있습니다. 대부분의 사용자는 설정할 필요가 없습니다. {command}를 실행하고 바로 시작하세요."
},
"quickStart": {
"title": "Quick Start"
},
"configLocations": {
"title": "Config File Locations",
"projectLevel": "(프로젝트 레벨)",
"userLevel": "(사용자 레벨)",
"jsonc": "JSONC가 지원되어 주석과 후행 쉼표를 사용할 수 있습니다."
},
"agentsSection": {
"title": "Agents",
"description": "내장된 Agent의 특정 동작을 설정합니다: Sisyphus, Hephaestus, Oracle, Librarian, Explore, Multimodal Looker, Prometheus, Metis, Momus, Atlas, Sisyphus Junior.",
"overrideOptions": "Override 옵션",
"permissions": "Permissions",
"options": {
"model": "모델 식별자 (예: openai/gpt-4o)",
"variant": "모델 변형 (max, high, medium, low)",
"category": "카테고리에서 설정 상속",
"temperature": "샘플링 온도 (0-2)",
"topP": "Top-p 샘플링 (0-1)",
"prompt": "시스템 프롬프트 완전히 재정의",
"promptAppend": "시스템 프롬프트에 텍스트 추가",
"tools": "특정 도구 활성화 또는 비활성화",
"disable": "이 Agent 비활성화",
"maxTokens": "응답의 최대 토큰 수",
"thinking": "확장 사고 설정",
"reasoningEffort": "추론 노력: low, medium, high, xhigh"
},
"permissionValues": "ask / allow / deny",
"permissionDescriptions": {
"edit": "파일 편집 기능",
"bash": "Bash 명령어 실행",
"webfetch": "웹 요청 기능",
"doomLoop": "무한 루프 재정의",
"externalDirectory": "프로젝트 외부 파일 접근"
}
},
"categoriesSection": {
"title": "Categories",
"description": "Categories를 사용하면 Agent가 상속할 수 있는 공유 설정을 정의할 수 있습니다.",
"availableOptions": "Categories 사용 가능 옵션: {options}.",
"categories": {
"visualEngineering": "프론트엔드, UI/UX, 디자인 작업",
"ultrabrain": "심층 논리적 추론",
"deep": "자율 문제 해결, 철저한 리서치",
"artistry": "창의적 작업",
"quick": "간단하고 빠른 작업",
"unspecifiedLow": "저노력 일반 작업",
"unspecifiedHigh": "고노력 일반 작업",
"writing": "문서 및 산문"
}
},
"skillsSection": {
"title": "Skills",
"description": "내장된 스킬에는 {playwright}, {agentBrowser}, {gitMaster}가 포함됩니다. 커스텀 스킬도 정의할 수 있습니다."
},
"backgroundTasksSection": {
"title": "Background Tasks",
"priority": "우선순위:",
"options": {
"defaultConcurrency": "기본 최대 동시 작업 수",
"staleTimeoutMs": "오래된 작업 타임아웃 (ms)",
"providerConcurrency": "프로바이더당 동시성 제한",
"modelConcurrency": "모델당 동시성 제한"
}
},
"hooksSection": {
"title": "Hooks",
"description": "Hooks를 사용하면 다양한 라이프사이클 지점에서 기능을 확장할 수 있습니다."
},
"mcpsSection": {
"title": "MCPs",
"websearch": {
"title": "websearch",
"description": "Exa로 구동되는 고품질 검색 결과."
},
"context7": {
"title": "context7",
"description": "문서 검색 및 컨텍스트 관리."
},
"grepApp": {
"title": "grep_app",
"description": "GitHub 코드 검색 통합."
}
},
"browserAutomationSection": {
"title": "Browser Automation",
"playwright": {
"tool": "playwright",
"description": "풀 브라우저 자동화 (기본값)",
"useCase": "테스트, 복잡한 상호작용"
},
"agentBrowser": {
"tool": "agent-browser",
"description": "가벼운 브라우저 Agent",
"useCase": "빠른 조회, 간단한 스크래핑"
}
},
"tmuxSection": {
"title": "Tmux Integration",
"options": {
"enabled": "Tmux 통합 활성화",
"layout": "Tmux 창 레이아웃",
"mainPaneSize": "메인 창 크기"
}
},
"gitMasterSection": {
"title": "Git Master",
"options": {
"commitFooter": "커밋 메시지에 추가할 텍스트",
"includeCoAuthoredBy": "Co-authored-by 트레일러 추가"
}
},
"commentCheckerSection": {
"title": "Comment Checker",
"description": "코드의 주석을 검증합니다. 커스텀 프롬프트에서 {placeholder} 자리 표시자를 사용하세요."
},
"experimentalSection": {
"title": "Experimental Features",
"options": {
"aggressiveTruncation": "출력을 적극적으로 잘라내기",
"autoResume": "중단된 작업 자동 재개",
"preemptiveCompaction": "제한 전 컨텍스트 압축",
"truncateAllToolOutputs": "모든 도구 출력 잘라내기"
},
"dynamicPruning": {
"trigger": "dynamic_context_pruning",
"description": "컨텍스트 윈도우 사용량을 효율적으로 관리하기 위한 동적 가지치기 규칙을 설정합니다."
}
},
"lspSection": {
"title": "LSP Configuration",
"options": {
"command": "LSP 서버 명령어",
"extensions": "매칭할 파일 확장자",
"priority": "서버 우선순위",
"env": "환경 변수",
"initialization": "초기화 옵션",
"disabled": "이 LSP 비활성화"
}
},
"envVarsSection": {
"title": "Environment Variables",
"opencodeConfigDir": {
"name": "OPENCODE_CONFIG_DIR",
"description": "기본 설정 디렉토리 경로를 재정의합니다."
}
},
"footer": "Oh My OpenAgent Documentation © {year}"
"searchPlaceholder": "문서 검색..."
},
"manifesto": {
"badge": "Manifesto",