diff --git a/content/docs/components/meta.json b/content/docs/components/meta.json new file mode 100644 index 0000000..91bb560 --- /dev/null +++ b/content/docs/components/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Components", + "pages": [ + "objectui-embed" + ] +} diff --git a/content/docs/components/objectui-embed.mdx b/content/docs/components/objectui-embed.mdx new file mode 100644 index 0000000..b8dacd6 --- /dev/null +++ b/content/docs/components/objectui-embed.mdx @@ -0,0 +1,326 @@ +--- +title: ObjectUI Embed +description: Learn how to embed interactive ObjectUI components directly in your documentation. +--- + +import { Cpu, Code, Layout } from 'lucide-react'; + +# ObjectUI Embed + +One of ObjectDocs' most powerful features is the ability to embed live, interactive **ObjectUI** components directly within your Markdown documentation. + +## Overview + +ObjectUI is a low-code component library that renders interactive interfaces from JSON schemas. By embedding these components in your docs, you can: + +* **Demonstrate Live Examples**: Show working examples without screenshots +* **Interactive Tutorials**: Let users interact with components as they learn +* **Configuration Visualization**: Display how JSON schemas render as UI + + +ObjectUI integration allows you to showcase your low-code platform capabilities directly in the documentation, making it easier for users to understand how configurations translate to visual components. + + +## Basic Usage + +### JSON Schema Format + +ObjectUI components are defined using JSON schemas that describe the component type, properties, and behavior: + +```json +{ + "component": "ObjectGrid", + "props": { + "object": "contracts", + "columns": ["name", "amount", "status", "created_by"], + "filters": [ + { "field": "status", "operator": "=", "value": "active" } + ] + } +} +``` + +### Component Types + + + } title="ObjectGrid"> + Display data in a customizable table with sorting, filtering, and pagination + + } title="ObjectForm"> + Render forms with validation based on object schema definitions + + } title="ObjectDetail"> + Show detailed view of a single record with related data + + + +## Example: Object Grid + +Here's how to embed a data grid showing contract information: + +```json title="contract-grid.json" +{ + "component": "ObjectGrid", + "props": { + "object": "contracts", + "columns": [ + { "field": "name", "label": "Contract Name" }, + { "field": "amount", "label": "Amount", "type": "currency" }, + { "field": "status", "label": "Status", "type": "badge" }, + { "field": "created_by", "label": "Created By" } + ], + "filters": [ + { + "field": "status", + "operator": "in", + "value": ["active", "pending"] + } + ], + "sort": { + "field": "created_at", + "order": "desc" + }, + "pageSize": 10, + "searchable": true + } +} +``` + +This configuration will render an interactive grid with: +* Four visible columns (name, amount, status, creator) +* Filtering for active and pending contracts +* Sorting by creation date (newest first) +* Search functionality +* Pagination with 10 items per page + +## Example: Object Form + +Create an embedded form for data entry: + +```json title="contract-form.json" +{ + "component": "ObjectForm", + "props": { + "object": "contracts", + "mode": "create", + "fields": [ + { + "field": "name", + "label": "Contract Name", + "required": true, + "placeholder": "Enter contract name" + }, + { + "field": "amount", + "label": "Contract Amount", + "type": "number", + "required": true, + "min": 0 + }, + { + "field": "status", + "label": "Status", + "type": "select", + "options": [ + { "label": "Draft", "value": "draft" }, + { "label": "Active", "value": "active" }, + { "label": "Completed", "value": "completed" } + ], + "default": "draft" + }, + { + "field": "description", + "label": "Description", + "type": "textarea", + "rows": 4 + } + ], + "submitButton": { + "text": "Create Contract", + "color": "primary" + } + } +} +``` + +## Schema Validation + +ObjectUI components automatically validate against the object schema defined in your ObjectQL configuration. This ensures: + +* Type safety +* Required field validation +* Format validation (email, URL, etc.) +* Custom business rules + + +Make sure your object schemas are properly defined in ObjectQL before embedding ObjectUI components. Missing schema definitions will result in validation errors. + + +## Advanced Features + +### Conditional Rendering + +Show/hide fields based on other field values: + +```json +{ + "component": "ObjectForm", + "props": { + "object": "contracts", + "fields": [ + { + "field": "type", + "type": "select", + "options": ["fixed", "hourly"] + }, + { + "field": "fixed_amount", + "type": "number", + "visible": { + "conditions": [ + { "field": "type", "operator": "=", "value": "fixed" } + ] + } + }, + { + "field": "hourly_rate", + "type": "number", + "visible": { + "conditions": [ + { "field": "type", "operator": "=", "value": "hourly" } + ] + } + } + ] + } +} +``` + +### Related Objects + +Display related data using lookups: + +```json +{ + "component": "ObjectGrid", + "props": { + "object": "contracts", + "columns": [ + "name", + { + "field": "customer", + "type": "lookup", + "related": "customers", + "displayField": "company_name" + }, + { + "field": "owner", + "type": "lookup", + "related": "users", + "displayField": "full_name" + } + ] + } +} +``` + +### Custom Actions + +Add custom buttons and actions: + +```json +{ + "component": "ObjectGrid", + "props": { + "object": "contracts", + "actions": [ + { + "label": "Approve", + "icon": "check", + "color": "success", + "onClick": "approve_contract", + "visible": { + "conditions": [ + { "field": "status", "operator": "=", "value": "pending" } + ] + } + }, + { + "label": "Reject", + "icon": "x", + "color": "danger", + "onClick": "reject_contract" + } + ] + } +} +``` + +## Best Practices + + +### Keep Examples Simple + +Start with basic configurations and gradually introduce complexity. Users should be able to understand the example at a glance. + +### Provide Real Data + +Use realistic sample data that demonstrates actual use cases rather than generic "test" data. + +### Document All Props + +Always explain what each property does, especially for complex configurations. + +### Test Interactivity + +Before publishing, interact with embedded components to ensure they work as expected. + + +## Integration with Steedos + +ObjectUI seamlessly integrates with **Steedos** metadata, allowing you to: + +* Reference existing object definitions +* Use Steedos permissions and validation rules +* Trigger Steedos workflows +* Connect to live Steedos data sources + +```json +{ + "component": "ObjectGrid", + "props": { + "object": "contracts", + "dataSource": "steedos", + "endpoint": "https://api.steedos.com/api/v4", + "filters": [ + { + "field": "space", + "operator": "=", + "value": "${current_space_id}" + } + ] + } +} +``` + +## Limitations + + +**Current Limitations:** + +* ObjectUI components require ObjectQL schema definitions +* Some advanced features may require Steedos backend +* Real-time updates need websocket configuration +* File uploads require storage configuration + + +## Next Steps + + + + Learn more about configuring ObjectDocs + + + Understand the underlying architecture + + diff --git a/content/docs/getting-started/architecture.mdx b/content/docs/getting-started/architecture.mdx new file mode 100644 index 0000000..af67693 --- /dev/null +++ b/content/docs/getting-started/architecture.mdx @@ -0,0 +1,184 @@ +--- +title: Architecture +description: Deep dive into ObjectDocs architecture, directory structure, and data flow. +--- + +import { Layers, FileJson, Code, FileText } from 'lucide-react'; + +# Architecture + +ObjectDocs is built on a strict **Separation of Concerns** philosophy that separates presentation, configuration, and content into distinct layers. + +## Core Principles + +### 1. Configuration as Code + +Unlike traditional documentation sites where structure is hardcoded in React components, ObjectDocs treats documentation organization as **data**. + + + } title="Metadata-Driven"> + Navigation, sidebars, and page ordering are defined in JSON files, not React code. + + } title="Logic-Free Views"> + React components in `app/` are purely presentational and consume configuration. + + + +### 2. Three-Layer Architecture + +```text +┌─────────────────────────────────────────┐ +│ Content Layer (MDX) │ ← Technical Writers +│ /content/docs/**/*.mdx │ +└─────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ Configuration Layer (JSON) │ ← Platform Architects +│ /content/**/meta.json │ +│ /packages/site/objectdocs.json │ +└─────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ Presentation Layer (React) │ ← Frontend Engineers +│ /packages/site/app/** │ +└─────────────────────────────────────────┘ +``` + +## Directory Structure + +### Content Directory + +```text +content/ +└── docs/ + ├── meta.json # Root navigation structure + ├── index.mdx # Documentation home page + ├── getting-started/ + │ ├── meta.json # Getting Started section structure + │ ├── installation.mdx + │ ├── architecture.mdx + │ └── configuration.mdx + └── components/ + ├── meta.json # Components section structure + └── objectui-embed.mdx +``` + + +**Important**: The sidebar structure is defined entirely by `meta.json` files. Never modify React components to change page ordering. + + +### Site Package + +```text +packages/site/ +├── app/ # Next.js App Router +│ ├── [lang]/ +│ │ ├── docs/ +│ │ │ ├── [[...slug]]/ +│ │ │ │ └── page.tsx # Dynamic doc page +│ │ │ └── layout.tsx # Docs layout wrapper +│ │ ├── layout.tsx # Language layout +│ │ └── page.tsx # Homepage redirect +│ ├── layout.config.tsx # Layout configuration +│ └── layout.tsx # Root layout +├── lib/ +│ ├── source.ts # Content source configuration +│ └── site-config.ts # Site config loader +├── objectdocs.json # Global site configuration +└── source.config.ts # Fumadocs source config +``` + +## Data Flow + +### 1. Content Loading + +```mermaid +graph LR + A[MDX Files] --> B[Fumadocs] + B --> C[source.getPageTree] + C --> D[DocsLayout] + D --> E[Rendered Page] +``` + +1. **MDX files** in `content/docs/` are processed by Fumadocs +2. **meta.json** files define the navigation tree structure +3. **source.getPageTree()** generates the sidebar tree +4. **DocsLayout** component renders the final layout + +### 2. Configuration Loading + +```typescript +// packages/site/lib/site-config.ts +import siteConfig from '../objectdocs.json'; + +export { siteConfig }; +``` + +The `objectdocs.json` file is imported and used throughout the application to configure: +* Navigation bar links +* Branding (logo, theme colors) +* Sidebar behavior +* Footer content +* TOC settings + +## Key Concepts + +### Meta.json Format + +Each directory can have a `meta.json` file that controls the sidebar structure: + +```json +{ + "title": "Section Title", + "pages": [ + "page-slug", + "another-page", + "---Separator---", + "subsection" + ] +} +``` + +* **title**: Display name in the sidebar +* **pages**: Array of page slugs in the desired order +* **Separators**: Use `---Title---` format for visual separators + +### Page Frontmatter + +Every MDX file should include frontmatter: + +```mdx +--- +title: Page Title +description: Brief description for SEO and cards +--- + +# Content starts here +``` + +## Framework Stack + + + }> + App Router with Server Components for optimal performance + + }> + Documentation middleware for MDX processing and tree generation + + }> + Full type safety across content, config, and components + + + +## Next Steps + +Now that you understand the architecture, learn how to configure your site: + + + + Customize navigation, branding, and features + + + Embed interactive ObjectUI components + + diff --git a/content/docs/getting-started/configuration.mdx b/content/docs/getting-started/configuration.mdx new file mode 100644 index 0000000..59c36ae --- /dev/null +++ b/content/docs/getting-started/configuration.mdx @@ -0,0 +1,375 @@ +--- +title: Configuration +description: Learn how to customize your ObjectDocs site through objectdocs.json and meta.json files. +--- + +import { Settings, Palette, Navigation, Layout } from 'lucide-react'; + +# Configuration + +ObjectDocs follows a **Configuration as Code** approach. All site settings are defined in JSON files, making it easy to version control and collaborate. + +## Global Configuration + +### objectdocs.json + +The main configuration file is located at `packages/site/objectdocs.json`. This file controls global settings for your entire documentation site. + +```json +{ + "meta": { + "title": "ObjectStack Docs", + "description": "Enterprise-grade low-code platform documentation", + "url": "https://docs.objectstack.ai", + "favicon": "/favicon.ico" + }, + "i18n": { + "enabled": true, + "defaultLanguage": "en", + "languages": ["en", "cn"] + }, + "branding": { + "logo": { + "text": "ObjectStack", + "light": "/logo.svg", + "dark": "/logo.svg" + }, + "theme": { + "accentColor": "blue", + "radius": "0.5rem" + } + }, + "layout": { + "navbar": { + "enabled": true, + "transparentMode": "top", + "links": [ + { + "text": "Home", + "url": "https://www.objectstack.ai", + "external": true + } + ], + "socials": [ + { "platform": "github", "url": "https://github.com/objectstack-ai/" } + ] + }, + "sidebar": { + "enabled": true, + "prefetch": true, + "defaultOpenLevel": 1, + "collapsible": true + }, + "toc": { + "enabled": true, + "depth": 3 + }, + "footer": { + "enabled": false, + "copyright": "© 2026 ObjectStack Inc." + } + }, + "page": { + "showLastUpdate": true, + "showEditLink": true, + "repoBaseUrl": "https://github.com/objectstack-ai/docs" + }, + "content": { + "math": false, + "imageZoom": true, + "codeBlock": { + "theme": "vesper", + "showLineNumbers": true + } + } +} +``` + +## Configuration Sections + +### Meta Settings + + + } title="Basic Info"> + Configure site title, description, URL, and favicon + + } title="Branding"> + Customize logo, theme colors, and visual style + + + +#### meta + +```json +{ + "meta": { + "title": "Your Site Title", + "description": "Site description for SEO", + "url": "https://docs.example.com", + "favicon": "/favicon.ico" + } +} +``` + +### Internationalization (i18n) + +Enable multi-language support: + +```json +{ + "i18n": { + "enabled": true, + "defaultLanguage": "en", + "languages": ["en", "cn", "es", "fr"] + } +} +``` + +When enabled, ObjectDocs will: +* Create language-specific routes (`/en/docs`, `/cn/docs`) +* Look for translated content in language-specific directories +* Display language switcher in the navbar + +### Branding + +#### Logo Configuration + +```json +{ + "branding": { + "logo": { + "text": "Your Brand", + "light": "/logo-light.svg", + "dark": "/logo-dark.svg" + } + } +} +``` + +* **text**: Displayed next to the logo image +* **light**: Logo for light mode +* **dark**: Logo for dark mode (optional, falls back to light) + +#### Theme + +```json +{ + "branding": { + "theme": { + "accentColor": "blue", + "radius": "0.5rem" + } + } +} +``` + +* **accentColor**: Primary theme color (blue, purple, green, etc.) +* **radius**: Border radius for UI components + +### Layout Configuration + +#### Navbar + + + } title="Navigation Links"> + Add custom links to the top navigation bar + + } title="Social Links"> + Connect to GitHub, Twitter, and other platforms + + + +```json +{ + "layout": { + "navbar": { + "enabled": true, + "transparentMode": "top", + "links": [ + { + "text": "Guide", + "url": "/docs", + "external": false + }, + { + "text": "Blog", + "url": "https://blog.example.com", + "external": true + } + ], + "socials": [ + { "platform": "github", "url": "https://github.com/yourusername" }, + { "platform": "twitter", "url": "https://twitter.com/yourusername" } + ] + } + } +} +``` + +* **transparentMode**: `"top"` | `"always"` | `"none"` +* **links**: Array of navigation links +* **socials**: Social platform links (supports github, twitter, discord, etc.) + +#### Sidebar + +```json +{ + "layout": { + "sidebar": { + "enabled": true, + "prefetch": true, + "defaultOpenLevel": 1, + "collapsible": true, + "tabs": [] + } + } +} +``` + +* **prefetch**: Prefetch linked pages for faster navigation +* **defaultOpenLevel**: How many levels to expand by default (0 = collapsed, 1 = first level, etc.) +* **collapsible**: Allow users to collapse sidebar sections +* **tabs**: Optional sidebar tabs for multi-product docs + +#### Table of Contents (TOC) + +```json +{ + "layout": { + "toc": { + "enabled": true, + "depth": 3 + } + } +} +``` + +* **depth**: Maximum heading level to show (1-6) + +### Page Settings + +```json +{ + "page": { + "showLastUpdate": true, + "showEditLink": true, + "repoBaseUrl": "https://github.com/yourusername/yourrepo" + } +} +``` + +* **showLastUpdate**: Display last modified date from git +* **showEditLink**: Show "Edit this page" link +* **repoBaseUrl**: GitHub repository URL for edit links + +### Content Settings + +```json +{ + "content": { + "math": false, + "imageZoom": true, + "codeBlock": { + "theme": "vesper", + "showLineNumbers": true + } + } +} +``` + +* **math**: Enable LaTeX math rendering +* **imageZoom**: Allow users to click images to zoom +* **codeBlock.theme**: Syntax highlighting theme +* **codeBlock.showLineNumbers**: Display line numbers in code blocks + +## Local Configuration + +### meta.json + +Each directory in `content/docs/` can have a `meta.json` file to control its sidebar structure: + +```json +{ + "title": "Section Title", + "pages": [ + "first-page", + "second-page", + "---Subsection---", + "nested-directory" + ] +} +``` + + +**Critical**: The sidebar structure is **entirely** controlled by `meta.json` files. Never edit React components to change page ordering. + + +### Page Order + +The order of items in the `pages` array determines the sidebar order: + +```json +{ + "title": "Getting Started", + "pages": [ + "installation", // Appears first + "architecture", // Appears second + "configuration" // Appears third + ] +} +``` + +### Separators + +Add visual separators in the sidebar: + +```json +{ + "pages": [ + "intro", + "---Basic Guides---", + "guide-1", + "guide-2", + "---Advanced---", + "advanced-1" + ] +} +``` + +## Best Practices + + +### Keep Configuration DRY + +Don't repeat configuration across multiple files. Use the global `objectdocs.json` for site-wide settings. + +### Use Semantic Names + +Choose descriptive names for page slugs that reflect the content: +* ✅ `installation.mdx` +* ✅ `api-reference.mdx` +* ❌ `page1.mdx` +* ❌ `doc.mdx` + +### Version Control Everything + +All configuration is in JSON files, making it easy to: +* Track changes in git +* Review configuration updates +* Roll back if needed + +### Test Locally + +Always run `pnpm dev` to verify configuration changes before deploying. + + +## Next Steps + + + + Understand how configuration flows through the system + + + Learn about available components for your content + + diff --git a/content/docs/getting-started/installation.mdx b/content/docs/getting-started/installation.mdx new file mode 100644 index 0000000..a2ec0be --- /dev/null +++ b/content/docs/getting-started/installation.mdx @@ -0,0 +1,94 @@ +--- +title: Installation +description: Install ObjectDocs and create your first documentation site in under 5 minutes. +--- + +import { Terminal, Package, Rocket } from 'lucide-react'; + +# Installation + +Get started with ObjectDocs in just a few simple steps. + +## Prerequisites + +Before you begin, ensure you have the following installed on your system: + +* **Node.js** 18.17 or later +* **pnpm** 8.0 or later (recommended package manager) + + +While ObjectDocs works with npm and yarn, we strongly recommend **pnpm** for its superior performance and workspace support. + + +## Quick Start + +### 1. Clone the Repository + +```bash +git clone https://github.com/objectstack-ai/objectdocs.git +cd objectdocs +``` + +### 2. Install Dependencies + +```bash +pnpm install +``` + +This command will install all required dependencies for both the main project and all packages in the monorepo workspace. + +### 3. Run Development Server + +```bash +pnpm dev +``` + +Open [http://localhost:3000](http://localhost:3000) in your browser to see your documentation site. + + +🎉 **Success!** Your ObjectDocs site is now running locally. + + +## Project Structure + +After installation, you'll have the following structure: + +```text +objectdocs/ +├── content/ # Documentation content +│ └── docs/ +│ ├── meta.json # Navigation structure +│ └── index.mdx # Home page +├── packages/ +│ ├── cli/ # ObjectDocs CLI tool +│ └── site/ # Main documentation site +│ ├── app/ # Next.js app directory +│ ├── lib/ # Utility functions +│ └── objectdocs.json # Site configuration +└── package.json +``` + +## Build for Production + +To create a production build: + +```bash +pnpm build +``` + +To start the production server: + +```bash +pnpm start +``` + +## Next Steps + + + }> + Understand the core concepts and directory structure + + }> + Learn how to customize your documentation site + + diff --git a/content/docs/getting-started/meta.json b/content/docs/getting-started/meta.json new file mode 100644 index 0000000..356a6f0 --- /dev/null +++ b/content/docs/getting-started/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Getting Started", + "pages": [ + "installation", + "architecture", + "configuration" + ] +} diff --git a/content/docs/meta.json b/content/docs/meta.json new file mode 100644 index 0000000..203333e --- /dev/null +++ b/content/docs/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Documentation", + "pages": [ + "index", + "getting-started", + "components" + ] +}