diff --git a/content/docs/design.mdx b/content/docs/design.mdx new file mode 100644 index 0000000..12b5450 --- /dev/null +++ b/content/docs/design.mdx @@ -0,0 +1,301 @@ +--- +title: System Design +description: Complete system design document for ObjectDocs — architecture, technical decisions, and component overview. +--- + +import { FileJson, Layers, Cpu, Zap, GitBranch, Package, Globe, Code } from 'lucide-react'; + +# System Design Document + +This document provides a comprehensive technical design overview of ObjectDocs, covering the system architecture, package structure, data flow, and key design decisions. + +**Version**: v0.2.12 | **Last Updated**: 2026-02-08 + +## 1. System Overview + +ObjectDocs is a **metadata-driven documentation engine** built on Next.js and Fumadocs, designed for the ObjectStack low-code ecosystem. It follows a strict **Configuration as Code** philosophy where documentation structure is defined by data (JSON), not code (React). + +### Design Goals + + +} title="Metadata-Driven"> +Navigation, sidebars, and page ordering are defined entirely through `meta.json` files and `docs.site.json` configuration. Content creators never need to touch React code. + +} title="Separation of Concerns"> +The system strictly separates three layers: **Presentation** (React/Next.js site engine), **Configuration** (JSON files), and **Content** (MDX documents). + +} title="Monorepo Architecture"> +The project is organized as a pnpm workspace monorepo with two core packages (`@objectdocs/cli` and `@objectdocs/site`) plus a shared content layer. + +} title="i18n-First"> +Multi-language support is built into the core architecture, with language-specific MDX files and pre-built UI translations for 6 languages. + + + +## 2. Architecture Overview + +### 2.1 High-Level Architecture + +```text +┌─────────────────────────────────────────────────────────┐ +│ ObjectDocs System │ +├──────────────┬──────────────────┬───────────────────────┤ +│ @objectdocs │ @objectdocs │ Content Layer │ +│ /cli │ /site │ │ +│ │ │ │ +│ Commands: │ Next.js 16 + │ content/ │ +│ • init │ Fumadocs 16 │ ├── docs.site.json │ +│ • dev │ │ ├── docs/ │ +│ • build │ App Router │ │ ├── meta.json │ +│ • start │ React Server │ │ ├── index.mdx │ +│ • translate │ Components │ │ └── ... │ +│ │ │ └── public/ │ +├──────────────┼──────────────────┼───────────────────────┤ +│ CLI Layer │ Presentation │ Data Layer │ +│ (Tooling) │ Layer │ (Configuration + │ +│ │ (Rendering) │ Content) │ +└──────────────┴──────────────────┴───────────────────────┘ +``` + +### 2.2 Package Dependency Graph + +```text +Root Workspace (objectdocs v1.0.0) +├── @objectdocs/cli (v0.2.12) +│ ├── depends on: @objectdocs/site (workspace:*) +│ ├── cac (CLI framework) +│ ├── openai (AI translation) +│ └── dotenv (environment config) +└── @objectdocs/site (v0.2.12) + ├── next (^16.1.2) + ├── fumadocs-core (^16.4.7) + ├── fumadocs-ui (^16.4.7) + ├── fumadocs-mdx (^14.2.5) + ├── react (^19.2.3) + ├── tailwindcss (^4.1.18) + └── typescript (^5.9.3) +``` + +## 3. Core Components + +### 3.1 CLI Package (`@objectdocs/cli`) + +The CLI is the primary developer interface for ObjectDocs. Built with the [CAC](https://github.com/cacjs/cac) framework, it provides 5 commands: + +| Command | Purpose | Key Behavior | +|---------|---------|-------------| +| `init` | Initialize a new docs project | Copies `@objectdocs/site` to `content/.fumadocs`, installs deps, updates `.gitignore` | +| `dev` | Start development server | Runs on port 7777, watches `docs.site.json` for changes, syncs public assets | +| `build` | Build for production | Supports both static export (`out/`) and dynamic standalone (`.next/`) modes | +| `start` | Start production server | Static mode uses `serve`, dynamic mode uses Next.js server | +| `translate` | AI-powered translation | Uses OpenAI API, supports `--all` flag, generates language-specific `.mdx` files | + +**Design Decision**: The CLI copies the entire `@objectdocs/site` package into `content/.fumadocs` during init rather than using it as a runtime dependency. This ensures complete isolation between the documentation engine and user content, and allows the site to be customized without affecting the package. + +### 3.2 Site Package (`@objectdocs/site`) + +The site package is a complete Next.js application template that serves as the documentation rendering engine. + +**Key Components**: + +| Component | File | Responsibility | +|-----------|------|---------------| +| Root Layout | `app/layout.tsx` | HTML shell, providers, global styles | +| Language Router | `app/[lang]/layout.tsx` | i18n layout with Fumadocs provider | +| Docs Pages | `app/[lang]/docs/[[...slug]]/page.tsx` | MDX rendering, TOC, navigation | +| Search API | `app/api/search/route.ts` | Full-text search endpoint | +| i18n Config | `lib/i18n.ts` | Language definitions and UI translations | +| Site Config | `lib/config.ts` | Loads and merges `docs.site.json` | +| Source Loader | `lib/source.ts` | Fumadocs content source with i18n | + +### 3.3 Content Layer + +The content layer is the user-facing data that defines the documentation site: + +```text +content/ +├── docs.site.json # Global site configuration +│ ├── branding # Logo, name, theme colors +│ ├── links # Navbar navigation links +│ ├── sidebar # Sidebar behavior config +│ ├── toc # Table of contents settings +│ ├── footer # Footer copyright text +│ ├── page # Per-page features (edit link, last update) +│ ├── content # Content features (math, code theme) +│ ├── i18n # Language configuration +│ └── build # Build mode (export/standalone) +├── public/ # Static assets (images, fonts) +└── docs/ + ├── meta.json # Root navigation structure + ├── index.mdx # Homepage (English) + ├── index.cn.mdx # Homepage (Chinese) + └── getting-started/ + ├── meta.json # Section page ordering + ├── index.mdx # Section landing page + └── ... +``` + +## 4. Data Flow + +### 4.1 Build-Time Data Flow + + + +### Content Discovery +Fumadocs MDX source loader scans the `DOCS_DIR` directory for all `.mdx` files and `meta.json` files. Files are organized by language suffix (e.g., `.cn.mdx` for Chinese). + +### Configuration Merge +The site reads `docs.site.json` from the content directory and merges it with default configuration values in `lib/config.ts`. This produces the complete site configuration. + +### Navigation Tree Construction +`meta.json` files in each directory define the page ordering and section titles. Fumadocs builds a hierarchical navigation tree from these files. + +### MDX Compilation +Each `.mdx` file is compiled through the Fumadocs MDX pipeline with remark/rehype plugins, producing React Server Components. + +### Static Generation +Next.js App Router generates static pages for each route. In standalone mode, pages can be server-rendered with ISR support. + + + +### 4.2 Runtime Data Flow + +```text +User Request → Next.js Router → Language Detection → Page Resolution + → MDX Content Rendering (RSC) → Fumadocs UI Layout → HTML Response +``` + +### 4.3 Translation Data Flow + +```text +Source MDX → CLI translate command → OpenAI API → Translated MDX + → Language-specific file (e.g., .cn.mdx) → Content Discovery +``` + +## 5. Configuration System Design + +### 5.1 `docs.site.json` Schema + +The site configuration file supports the following sections: + +```json +{ + "site": { + "title": "Site title", + "description": "Site description", + "url": "https://example.com", + "favicon": "/favicon.ico" + }, + "branding": { + "name": "Brand Name", + "logo": { "light": "/logo-light.svg", "dark": "/logo-dark.svg" }, + "themeColor": "#7c3aed", + "borderRadius": "0.5rem" + }, + "links": [{ "text": "Home", "url": "/" }], + "sidebar": { "collapsible": true, "defaultOpenLevel": 1 }, + "toc": { "enabled": true, "depth": 3 }, + "footer": { "copyright": "© 2026" }, + "page": { + "lastUpdate": true, + "editOnGithub": { "owner": "org", "repo": "repo" } + }, + "content": { "codeTheme": "vesper", "imageZoom": true }, + "i18n": { + "defaultLanguage": "en", + "languages": ["en", "cn"] + }, + "build": { "mode": "export" } +} +``` + +### 5.2 `meta.json` Schema + +Each directory can contain a `meta.json` to control navigation: + +```json +{ + "title": "Section Title", + "pages": ["page-a", "page-b", "sub-directory"] +} +``` + +**Key Rule**: Sidebar navigation is **never** defined in React components. All navigation structure changes go through `meta.json` files. + +## 6. i18n Architecture + +### 6.1 Supported Languages + +| Code | Language | UI Translations | +|------|----------|----------------| +| `en` | English | ✅ Complete | +| `cn` | 中文 (Chinese) | ✅ Complete | +| `ja` | 日本語 (Japanese) | ✅ Complete | +| `fr` | Français (French) | ✅ Complete | +| `de` | Deutsch (German) | ✅ Complete | +| `es` | Español (Spanish) | ✅ Complete | + +### 6.2 Content Translation Strategy + +- **File-based**: Each language has its own MDX file (e.g., `index.mdx` for English, `index.cn.mdx` for Chinese) +- **Fallback**: If a translated file doesn't exist, the default language version is used +- **AI Translation**: The `translate` CLI command uses OpenAI to generate translations automatically +- **URL Routing**: Language prefix in URL path (`/en/docs/...`, `/cn/docs/...`) + +## 7. Deployment Design + +### 7.1 Build Modes + +| Mode | Output | Use Case | +|------|--------|----------| +| `export` (Static) | `out/` directory with HTML/CSS/JS | CDN hosting, GitHub Pages, Vercel static | +| `standalone` (Dynamic) | `.next/` with Node.js server | ISR, SSR, API routes, Vercel serverless | + +### 7.2 Vercel Deployment + +```text +GitHub Push → Vercel Build Hook → pnpm build → Next.js Build + → Static Assets + Serverless Functions → Edge CDN Distribution +``` + +**Key Design Decisions**: +- Standalone output mode for optimal Vercel serverless support +- Symlink-aware artifact copying to handle monorepo structures +- `vercel.json` routing configuration for clean URLs +- Preview deployments via GitHub Actions workflow + +### 7.3 CI/CD Pipeline + +| Workflow | Trigger | Purpose | +|----------|---------|---------| +| `ci.yml` | Push/PR | Build validation | +| `release.yml` | Push to main | Changesets NPM publishing | +| `preview.yml` | PR | Vercel preview deployment | +| `test-lifecycle.yml` | Push/PR | Full lifecycle testing | +| `link-check.yml` | PR | Content link validation | + +## 8. Technology Stack + +| Layer | Technology | Version | +|-------|-----------|---------| +| Runtime | Next.js (App Router) | ^16.1.2 | +| UI Framework | React (Server Components) | ^19.2.3 | +| Documentation Engine | Fumadocs | ^16.4.7 | +| Styling | Tailwind CSS | ^4.1.18 | +| Language | TypeScript | ^5.9.3 | +| Package Manager | pnpm | Workspace monorepo | +| AI Integration | OpenAI API | ^4.0.0 | +| CLI Framework | CAC | ^6.7.14 | +| Content Format | MDX | Via fumadocs-mdx | +| Deployment | Vercel | Serverless/Edge | + +## 9. Security Considerations + +- **No hardcoded secrets**: All API keys (e.g., OpenAI) are loaded via environment variables +- **Server Components by default**: Minimizes client-side JavaScript exposure +- **Content isolation**: Documentation content is separated from the rendering engine +- **Dependency management**: Automated via Changesets with locked versions + + +This design document reflects the current state of ObjectDocs v0.2.12. It will be updated as the system evolves. For the feature roadmap, see the [Development Roadmap](/docs/development-plan). + diff --git a/content/docs/development-plan.mdx b/content/docs/development-plan.mdx index 996fcef..5645cf0 100644 --- a/content/docs/development-plan.mdx +++ b/content/docs/development-plan.mdx @@ -3,12 +3,14 @@ title: Development Roadmap description: ObjectDocs development plan and feature roadmap for GitHub-based documentation with Vercel deployment --- -import { Code, Sparkles, Globe, Shield, GitBranch, Rocket } from 'lucide-react'; +import { Code, Sparkles, Globe, Shield, GitBranch, Rocket, CheckCircle } from 'lucide-react'; # ObjectDocs Development Roadmap This document outlines the development plan and feature roadmap for ObjectDocs, a GitHub-native documentation engine optimized for Vercel deployment. +**Current Version**: v0.2.12 | **Last Updated**: 2026-02-08 + ## 🎯 Core Mission ObjectDocs is purpose-built for **GitHub-based repository documentation** with seamless **Vercel deployment integration**. Our core objectives: @@ -17,26 +19,42 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s 2. **Zero-Config Deployment**: Push to GitHub, auto-deploy to Vercel with optimal caching and CDN distribution 3. **Developer-First**: Treat documentation as code—version controlled, peer-reviewed, and CI/CD integrated +## 📊 Overall Progress Summary + +| Package | Version | Status | +|---------|---------|--------| +| `@objectdocs/cli` | v0.2.12 | ✅ Stable | +| `@objectdocs/site` | v0.2.12 | ✅ Stable | +| Root Workspace | v1.0.0 | ✅ Active | + +| Phase | Status | Progress | +|-------|--------|----------| +| Phase 1: Core Platform & Deployment | ✅ Mostly Complete | ~80% | +| Phase 2: Developer Experience | 🟡 In Progress | ~30% | +| Phase 3: Advanced Features | ⬚ Planned | ~0% | + ## 📅 Development Roadmap -### Phase 1: GitHub Integration & Vercel Optimization (Q1 2026) +### Phase 1: Core Platform & Deployment (Q4 2025 – Q1 2026) -} title="GitHub-Native Features"> +} title="GitHub-Native Features"> **Goal**: Deep integration with GitHub repository workflows +- [x] GitHub Actions workflows for automated builds and checks (CI, release, preview, test-lifecycle, link-check) +- [x] PR preview deployments via Vercel integration (`preview.yml` workflow) +- [x] Changesets-based versioned releases with automated NPM publishing - [ ] GitHub App for automated documentation syncing -- [ ] PR preview deployments via Vercel integration - [ ] GitHub Issues integration for documentation feedback -- [ ] GitHub Actions workflows for automated builds and checks - [ ] Branch-based documentation versioning -**Technical Implementation**: -- Use GitHub REST/GraphQL APIs for content fetching -- Implement Vercel Git integration hooks -- Create reusable GitHub Actions for linting and validation -- Support monorepo documentation with git submodules +**Implemented**: +- CI workflow (`ci.yml`) for build validation on push/PR +- Release workflow (`release.yml`) with Changesets for semantic versioning +- Preview workflow (`preview.yml`) for PR preview deployments +- Test lifecycle workflow (`test-lifecycle.yml`) for comprehensive testing +- Link check workflow (`link-check.yml`) for content validation @@ -44,40 +62,46 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s **Goal**: Optimize for Vercel's edge network and build system +- [x] Standalone output mode for Vercel/Docker support +- [x] Production deployment automation via GitHub Actions +- [x] `vercel.json` configuration for optimal routing +- [x] Preview deployments for every PR +- [x] Monorepo-aware build configuration - [ ] ISR (Incremental Static Regeneration) configuration - [ ] Edge Functions for dynamic content -- [ ] Optimal caching strategies (stale-while-revalidate) -- [ ] Preview deployments for every PR -- [ ] Production deployment automation +- [ ] Edge Middleware for A/B testing -**Technical Implementation**: -- Configure `vercel.json` for optimal routing -- Implement edge middleware for A/B testing -- Use Vercel Analytics for performance monitoring -- Integrate Vercel Image Optimization -- Set up custom domains with SSL automation +**Implemented**: +- `next.config.mjs` with standalone output mode +- Symlink-aware artifact copying for Vercel compatibility +- Both static export and dynamic (standalone) build modes +- Vercel deployment configuration in `vercel.json` -### Phase 2: Enhanced Developer Experience (Q2 2026) +### Phase 2: Enhanced Developer Experience (Q1 – Q2 2026) } title="CLI & Automation Tools"> **Goal**: Streamline repository-to-documentation workflow -- [ ] Enhanced ObjectDocs CLI with GitHub integration +- [x] Full-featured ObjectDocs CLI with 5 commands (init, dev, build, start, translate) +- [x] Zero-config project initialization (`objectdocs init`) +- [x] Hot-reload development server with config watching +- [x] Static and dynamic build modes - [ ] Automated content migration from README files - [ ] Code snippet extraction from repository files - [ ] API documentation generation from source code - [ ] Automated changelog generation from commits -**Technical Implementation**: -- Extend `@objectdocs/cli` with GitHub API features -- Use TypeScript AST parsing for API extraction -- Integrate conventional commits for changelog -- Support multi-repo documentation aggregation +**Implemented**: +- `init` — Copies site template, installs dependencies, configures `.gitignore` +- `dev` — Dev server on port 7777 with `docs.site.json` watching and asset sync +- `build` — Static/dynamic builds with artifact handling +- `start` — Production server (static via `serve` or dynamic via Next.js) +- `translate` — OpenAI-powered batch translation with `--all` flag @@ -85,22 +109,23 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s **Goal**: Leverage AI to enhance documentation quality +- [x] Automated translation support via OpenAI integration +- [x] Multi-language file generation (`.cn.mdx`, `.ja.mdx`, etc.) +- [x] CI-compatible translation with environment variables - [ ] AI-powered search with semantic understanding - [ ] Auto-generate documentation from code comments - [ ] Intelligent content suggestions based on repository - [ ] Documentation quality scoring and recommendations -- [ ] Automated translation support -**Technical Implementation**: -- Integrate OpenAI API or local LLM models -- Use vector databases (Pinecone/Weaviate) for semantic search -- Implement Markdown AST analysis for content quality -- Support embeddings for documentation similarity +**Implemented**: +- OpenAI API integration in `translate` command +- Support for `--all` flag to translate all content +- Environment variable configuration for CI pipelines -### Phase 3: Collaboration & Advanced Features (Q3 2026) +### Phase 3: Collaboration & Advanced Features (Q3 2026+) } title="Multi-Repository Documentation Hub"> @@ -113,7 +138,7 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s - [ ] Automated aggregation from multiple sources - [ ] Unified version management across repos -**Technical Implementation**: +**Technical Plan**: - GitHub Organization API integration - Implement repository discovery and indexing - Support GitHub Teams for access control @@ -131,7 +156,7 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s - [ ] Audit logging for documentation changes - [ ] GitHub Advanced Security integration -**Technical Implementation**: +**Technical Plan**: - Support GitHub Enterprise API endpoints - Integrate with GitHub's OIDC provider - Use GitHub's permission model for access control @@ -143,24 +168,35 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s ## 🔧 Technical Infrastructure ### GitHub Workflow Optimization +- [x] GitHub Actions for continuous deployment (CI, release, preview) +- [x] Pull request checks and status badges +- [x] Automated release process via Changesets - [ ] Automated dependency updates via Dependabot -- [ ] GitHub Actions for continuous deployment -- [ ] Pull request checks and status badges - [ ] Automated release notes from git tags - [ ] Issue templates for documentation requests +### Content & i18n System +- [x] Full i18n support with 6 languages (EN, CN, JA, FR, DE, ES) +- [x] Language-specific MDX file routing (`.en.mdx`, `.cn.mdx`) +- [x] Pre-built UI translations for all supported languages +- [x] Configurable default language +- [x] AI-powered translation CLI command + ### Vercel Platform Features +- [x] Standalone output mode for serverless deployment +- [x] Search API endpoint (`/api/search`) - [ ] Edge Config for dynamic feature flags - [ ] Vercel KV for caching layer -- [ ] Serverless Functions for API endpoints - [ ] Web Analytics integration - [ ] A/B testing with Edge Middleware ### Performance & SEO +- [x] React Server Components for optimal performance +- [x] MDX static compilation - [ ] Lighthouse score optimization (95+ target) - [ ] Core Web Vitals monitoring -- [ ] Automatic sitemap generation from git history -- [ ] OpenGraph metadata from repository info +- [ ] Automatic sitemap generation +- [ ] OpenGraph metadata automation - [ ] Structured data for search engines ## 🚀 Deployment Architecture @@ -169,44 +205,43 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s ```yaml Repository Structure: ├── content/ # Documentation MDX files +│ ├── docs/ # MDX pages and meta.json +│ └── docs.site.json # Site configuration ├── .github/ │ └── workflows/ # CI/CD automation ├── vercel.json # Deployment configuration -└── docs.site.json # Site metadata +└── package.json # Root workspace ``` ### CI/CD Pipeline -1. **Push to GitHub** → Triggers Vercel build -2. **PR Created** → Generates preview deployment +1. **Push to GitHub** → Triggers CI build validation +2. **PR Created** → Generates preview deployment via Vercel 3. **Merge to main** → Auto-deploys to production -4. **Git Tag** → Creates versioned documentation - -## 📊 Priority Matrix - -| Priority | Description | Target | -|----------|-------------|--------| -| 🔴 Critical | GitHub integration, Vercel deployment | Q1 2026 | -| 🟡 High | Developer tools, performance optimization | Q2 2026 | -| 🟢 Medium | Advanced features, enterprise support | Q3 2026+ | +4. **Changeset merged** → Automated NPM release ## 🎯 Current Focus (Q1 2026) ### Active Development Tasks -1. **Vercel Deployment Optimization (🔴 Critical)** +1. **Design Documentation (✅ Complete)** - Target: February 2026 - - Status: In Progress - - Deliverables: ISR configuration, edge functions, caching strategy + - Status: Complete + - Deliverables: System design document, package overview, updated roadmap -2. **GitHub App Development (🔴 Critical)** +2. **ISR & Edge Functions (🟡 In Progress)** - Target: March 2026 - Status: In Planning - - Deliverables: OAuth app, webhook handlers, API integration + - Deliverables: ISR configuration, edge middleware, caching strategy -3. **CLI Enhancement (🟡 High)** - - Target: March 2026 +3. **Content Migration Tools (🟡 Planned)** + - Target: Q2 2026 - Status: In Planning - - Deliverables: GitHub integration commands, automation scripts + - Deliverables: README migration, code snippet extraction, API doc generation + +4. **GitHub App Development (⬚ Planned)** + - Target: Q3 2026 + - Status: Not Started + - Deliverables: OAuth app, webhook handlers, API integration ## 💡 Community & Contribution @@ -229,6 +264,7 @@ This roadmap is dynamic and will evolve based on community feedback and GitHub/V | Date | Changes | Author | |------|---------|--------| +| 2026-02-08 | Updated progress status, marked completed features, added package overview | Team | | 2026-01-18 | Created development roadmap focused on GitHub-Vercel integration | Team | --- diff --git a/content/docs/meta.json b/content/docs/meta.json index a5bc454..5ac96cc 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -3,6 +3,8 @@ "pages": [ "index", "getting-started", + "packages", + "design", "components", "integrations", "development-plan" diff --git a/content/docs/packages.mdx b/content/docs/packages.mdx new file mode 100644 index 0000000..ef05ec2 --- /dev/null +++ b/content/docs/packages.mdx @@ -0,0 +1,290 @@ +--- +title: Packages Overview +description: Complete overview of ObjectDocs software packages, their features, development status, and version history. +--- + +import { Package, Terminal, Layout, Zap, CheckCircle, Clock } from 'lucide-react'; + +# Packages Overview + +ObjectDocs is organized as a **pnpm workspace monorepo** with two core packages. This document provides a detailed overview of each package, its features, current status, and development history. + +**Current Version**: v0.2.12 | **Last Updated**: 2026-02-08 + +## Package Summary + +| Package | Version | Description | Status | +|---------|---------|-------------|--------| +| `@objectdocs/cli` | v0.2.12 | Command-line tool for building and managing documentation | ✅ Stable | +| `@objectdocs/site` | v0.2.12 | Next.js documentation site template and rendering engine | ✅ Stable | + +## @objectdocs/cli + + +} title="CLI Tool"> + +The primary developer interface for ObjectDocs. Provides commands for initializing, developing, building, and deploying documentation sites. + +- **Framework**: CAC (Command-line framework) +- **Language**: JavaScript/Node.js (ESM) +- **Entry Point**: `bin/cli.mjs` + + + + +### Commands + + + +### `objectdocs init` + +Initializes a new documentation project by copying the site template and setting up the development environment. + +**What it does**: +- Copies `@objectdocs/site` package to `content/.fumadocs` +- Creates `content/package.json` with dev/build/start scripts +- Installs dependencies in `content/.fumadocs` +- Updates `.gitignore` to exclude generated files + +### `objectdocs dev [docsDir]` + +Starts the development server with hot reload. + +**Features**: +- Default port: 7777 (configurable) +- Watches `docs.site.json` for changes and auto-restarts +- Syncs public assets to site engine +- Sets `DOCS_DIR` environment variable + +### `objectdocs build [docsDir]` + +Builds the documentation site for production. + +**Features**: +- Supports static export (`out/` directory) and dynamic standalone (`.next/`) modes +- Copies configuration and public assets +- Handles symlink-aware artifact copying for Vercel compatibility + +### `objectdocs start` + +Starts the production server. + +**Features**: +- Static mode: Serves from `out/` directory using `serve` +- Dynamic mode: Runs Next.js production server +- Configurable port + +### `objectdocs translate` + +AI-powered content translation using OpenAI. + +**Features**: +- Translates MDX content to configured languages +- `--all` flag for batch translation +- CI-compatible with environment variable configuration +- Generates language-specific files (e.g., `.cn.mdx`, `.ja.mdx`) + + + +### Dependencies + +| Dependency | Version | Purpose | +|-----------|---------|---------| +| `@objectdocs/site` | workspace:* | Site template for initialization | +| `cac` | ^6.7.14 | CLI framework | +| `openai` | ^4.0.0 | AI-powered translation | +| `dotenv` | ^16.4.5 | Environment variable loading | +| `typescript` | ^5.9.3 | TypeScript support | + +### Feature Status + +| Feature | Status | Notes | +|---------|--------|-------| +| Project initialization | ✅ Complete | Full `init` workflow | +| Development server | ✅ Complete | Hot reload, config watching | +| Production build | ✅ Complete | Static + dynamic modes | +| Production server | ✅ Complete | Static + dynamic serving | +| AI translation | ✅ Complete | OpenAI integration | +| GitHub integration | ⬚ Planned | Phase 2 | +| README migration | ⬚ Planned | Phase 2 | +| API doc generation | ⬚ Planned | Phase 2 | + +--- + +## @objectdocs/site + + +} title="Site Template"> + +A complete Next.js application template that serves as the documentation rendering engine. Built on Fumadocs with full i18n support. + +- **Framework**: Next.js 16 (App Router) + Fumadocs 16 +- **Styling**: Tailwind CSS 4 +- **Language**: TypeScript +- **React**: v19 (Server Components) + + + + +### Core Features + + +} title="Content Rendering"> + +- MDX compilation with remark/rehype plugins +- Code syntax highlighting (Vesper theme) +- Image zoom capability +- Built-in components: Callout, Card, Cards, Steps, Step +- Table of contents generation + + +} title="Site Engine"> + +- File-system based routing +- Full-text search API endpoint +- `meta.json`-driven navigation tree +- Configurable sidebar, navbar, and footer +- Dark mode support + + + + +### Architecture + +| Component | Path | Description | +|-----------|------|-------------| +| Root Layout | `app/layout.tsx` | HTML shell, global providers | +| Language Router | `app/[lang]/layout.tsx` | i18n layout with Fumadocs | +| Docs Pages | `app/[lang]/docs/[[...slug]]/page.tsx` | Dynamic MDX page rendering | +| Home Redirect | `app/[lang]/page.tsx` | Redirects to docs root | +| Search API | `app/api/search/route.ts` | Full-text search endpoint | +| i18n System | `lib/i18n.ts` | 6-language support with UI translations | +| Config Loader | `lib/config.ts` | `docs.site.json` parsing and defaults | +| Source Manager | `lib/source.ts` | Fumadocs content source with i18n | +| MDX Components | `mdx-components.tsx` | Custom component registry | +| Source Config | `source.config.ts` | Content directory and MDX plugin config | + +### i18n Support + +Pre-built UI translations for 6 languages: + +| Language | Code | TOC Label | Search | Last Update | +|----------|------|-----------|--------|-------------| +| English | `en` | "On this page" | "Search" | "Last updated on" | +| 中文 | `cn` | "目录" | "搜索" | "最后更新于" | +| 日本語 | `ja` | "目次" | "検索" | "最終更新" | +| Français | `fr` | "Sur cette page" | "Rechercher" | "Dernière mise à jour" | +| Deutsch | `de` | "Auf dieser Seite" | "Suchen" | "Zuletzt aktualisiert am" | +| Español | `es` | "En esta página" | "Buscar" | "Última actualización" | + +### Configuration Options + +The site reads from `docs.site.json` with support for: + +- **Site metadata**: title, description, URL, favicon +- **Branding**: name, logo (light/dark), theme color, border radius +- **Navigation**: navbar links with text, URL, icon, external flag +- **Sidebar**: collapsible, prefetch, default open level, tabs +- **Table of Contents**: enabled, depth +- **Footer**: copyright text +- **Page features**: last update timestamps, edit on GitHub links +- **Content**: code theme, image zoom, math support +- **i18n**: default language, language list +- **Build**: mode (export/standalone) + +### Dependencies + +| Dependency | Version | Purpose | +|-----------|---------|---------| +| `next` | ^16.1.2 | Application framework | +| `react` / `react-dom` | ^19.2.3 | UI rendering | +| `fumadocs-core` | ^16.4.7 | Documentation engine core | +| `fumadocs-ui` | ^16.4.7 | Documentation UI components | +| `fumadocs-mdx` | ^14.2.5 | MDX content processing | +| `tailwindcss` | ^4.1.18 | Utility-first CSS | +| `typescript` | ^5.9.3 | Type safety | +| `openai` | ^4.0.0 | AI features | +| `lucide-react` | ^0.562.0 | Icon library | + +### Feature Status + +| Feature | Status | Notes | +|---------|--------|-------| +| MDX rendering | ✅ Complete | Full Fumadocs pipeline | +| i18n (6 languages) | ✅ Complete | File-based + UI translations | +| Full-text search | ✅ Complete | API endpoint | +| Dark mode | ✅ Complete | Via Fumadocs UI | +| Code highlighting | ✅ Complete | Vesper theme | +| Image zoom | ✅ Complete | Configurable | +| Standalone output | ✅ Complete | Vercel/Docker ready | +| Static export | ✅ Complete | CDN-deployable | +| Config system | ✅ Complete | `docs.site.json` | +| ISR support | ⬚ Planned | Phase 1 | +| Edge Functions | ⬚ Planned | Phase 1 | +| Math rendering | ⬚ Planned | Config exists, not enabled | + +--- + +## Version History + +### v0.2.12 (Latest) +- Patch release for maintenance updates + +### v0.2.11 +- Fix: Handle broken symlinks during build copy to prevent ENOENT errors on Vercel + +### v0.2.10 +- Feat: Enable standalone output mode for better Vercel/Docker support + +### v0.2.9 +- Fix: Add `.source` path alias to `tsconfig.json` for generated file resolution + +### v0.2.8 +- Fix: Use `dereference: true` when copying `.next` directory to expand all symlinks + +### v0.2.7 +- Fix: Use relative import for generated content to avoid alias resolution issues in monorepos + +### v0.2.6 +- Fix: Copy `.next` directory instead of symlinking to support Vercel deployment + +### v0.2.5 +- Chore: Add `transpilePackages` configuration for monorepo module resolution + +### v0.2.4 +- Fix: Rename `proxy.ts` to `middleware.ts` to fix Next.js 16 build error + +### v0.2.3 +- Fix: Update package metadata for publishing + +### v0.2.2 +- Docs: Updated README with corrected configuration file names + +### v0.2.1 +- Bug fixes and improvements + +### v0.2.0 +- Initial release: Modern documentation engine built on Next.js 14 and Fumadocs + +### v0.1.0 +- Initial release with metadata-driven architecture, low-code component embedding, enterprise-grade UI, and multi-product support + +--- + +## Starter Template + +An example starter template is available in `examples/starter/` with: +- Pre-configured `docs.site.json` with ObjectStack branding +- Sample documentation structure +- Ready-to-run content with `meta.json` navigation + +```bash +# Quick start with the starter template +cp -r examples/starter my-docs +cd my-docs +npm init @objectdocs +``` + + +For detailed technical architecture, see the [System Design](/docs/design) document. For the feature roadmap, see the [Development Roadmap](/docs/development-plan). + diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4ab03ca..6484f9e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1,7 +1,7 @@ lockfileVersion: '9.0' settings: - autoInstallPeers: false + autoInstallPeers: true excludeLinksFromLockfile: false importers: @@ -413,89 +413,105 @@ packages: resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==} cpu: [arm64] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-arm@1.2.4': resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==} cpu: [arm] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-ppc64@1.2.4': resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==} cpu: [ppc64] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-riscv64@1.2.4': resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==} cpu: [riscv64] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-s390x@1.2.4': resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==} cpu: [s390x] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-x64@1.2.4': resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==} cpu: [x64] os: [linux] + libc: [glibc] '@img/sharp-libvips-linuxmusl-arm64@1.2.4': resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==} cpu: [arm64] os: [linux] + libc: [musl] '@img/sharp-libvips-linuxmusl-x64@1.2.4': resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==} cpu: [x64] os: [linux] + libc: [musl] '@img/sharp-linux-arm64@0.34.5': resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [arm64] os: [linux] + libc: [glibc] '@img/sharp-linux-arm@0.34.5': resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [arm] os: [linux] + libc: [glibc] '@img/sharp-linux-ppc64@0.34.5': resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [ppc64] os: [linux] + libc: [glibc] '@img/sharp-linux-riscv64@0.34.5': resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [riscv64] os: [linux] + libc: [glibc] '@img/sharp-linux-s390x@0.34.5': resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [s390x] os: [linux] + libc: [glibc] '@img/sharp-linux-x64@0.34.5': resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [x64] os: [linux] + libc: [glibc] '@img/sharp-linuxmusl-arm64@0.34.5': resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [arm64] os: [linux] + libc: [musl] '@img/sharp-linuxmusl-x64@0.34.5': resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [x64] os: [linux] + libc: [musl] '@img/sharp-wasm32@0.34.5': resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==} @@ -574,24 +590,28 @@ packages: engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [glibc] '@next/swc-linux-arm64-musl@16.1.2': resolution: {integrity: sha512-Sn6LxPIZcADe5AnqqMCfwBv6vRtDikhtrjwhu+19WM6jHZe31JDRcGuPZAlJrDk6aEbNBPUUAKmySJELkBOesg==} engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [musl] '@next/swc-linux-x64-gnu@16.1.2': resolution: {integrity: sha512-nwzesEQBfQIOOnQ7JArzB08w9qwvBQ7nC1i8gb0tiEFH94apzQM3IRpY19MlE8RBHxc9ArG26t1DEg2aaLaqVQ==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [glibc] '@next/swc-linux-x64-musl@16.1.2': resolution: {integrity: sha512-s60bLf16BDoICQHeKEm0lDgUNMsL1UpQCkRNZk08ZNnRpK0QUV+6TvVHuBcIA7oItzU0m7kVmXe8QjXngYxJVA==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [musl] '@next/swc-win32-arm64-msvc@16.1.2': resolution: {integrity: sha512-Sq8k4SZd8Y8EokKdz304TvMO9HoiwGzo0CTacaiN1bBtbJSQ1BIwKzNFeFdxOe93SHn1YGnKXG6Mq3N+tVooyQ==} @@ -1057,24 +1077,28 @@ packages: engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [glibc] '@tailwindcss/oxide-linux-arm64-musl@4.1.18': resolution: {integrity: sha512-1px92582HkPQlaaCkdRcio71p8bc8i/ap5807tPRDK/uw953cauQBT8c5tVGkOwrHMfc2Yh6UuxaH4vtTjGvHg==} engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [musl] '@tailwindcss/oxide-linux-x64-gnu@4.1.18': resolution: {integrity: sha512-v3gyT0ivkfBLoZGF9LyHmts0Isc8jHZyVcbzio6Wpzifg/+5ZJpDiRiUhDLkcr7f/r38SWNe7ucxmGW3j3Kb/g==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [glibc] '@tailwindcss/oxide-linux-x64-musl@4.1.18': resolution: {integrity: sha512-bhJ2y2OQNlcRwwgOAGMY0xTFStt4/wyU6pvI6LSuZpRgKQwxTec0/3Scu91O8ir7qCR3AuepQKLU/kX99FouqQ==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [musl] '@tailwindcss/oxide-wasm32-wasi@4.1.18': resolution: {integrity: sha512-LffYTvPjODiP6PT16oNeUQJzNVyJl1cjIebq/rWWBF+3eDst5JGEFSc5cWxyRCJ0Mxl+KyIkqRxk1XPEs9x8TA==} @@ -1733,24 +1757,28 @@ packages: engines: {node: '>= 12.0.0'} cpu: [arm64] os: [linux] + libc: [glibc] lightningcss-linux-arm64-musl@1.30.2: resolution: {integrity: sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==} engines: {node: '>= 12.0.0'} cpu: [arm64] os: [linux] + libc: [musl] lightningcss-linux-x64-gnu@1.30.2: resolution: {integrity: sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==} engines: {node: '>= 12.0.0'} cpu: [x64] os: [linux] + libc: [glibc] lightningcss-linux-x64-musl@1.30.2: resolution: {integrity: sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==} engines: {node: '>= 12.0.0'} cpu: [x64] os: [linux] + libc: [musl] lightningcss-win32-arm64-msvc@1.30.2: resolution: {integrity: sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==}