@opendocsdev/cli 0.2.0

package/src/engine/tailwind.config.mjs

@@ -0,0 +1,60 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  darkMode: "class",
+  content: [
+    "./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}",
+    // Also scan MDX files from the user's project directory
+    `${process.env.OPENDOCS_PROJECT_DIR || "."}/**/*.{md,mdx}`,
+  ],
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: [
+          "Geist Variable",
+          "-apple-system",
+          "BlinkMacSystemFont",
+          "Segoe UI",
+          "Roboto",
+          "sans-serif",
+        ],
+        mono: [
+          "Geist Mono Variable",
+          "ui-monospace",
+          "SFMono-Regular",
+          "Menlo",
+          "Monaco",
+          "Consolas",
+          "monospace",
+        ],
+      },
+      typography: {
+        DEFAULT: {
+          css: {
+            maxWidth: "none",
+            color: "inherit",
+            a: {
+              color: "var(--color-primary)",
+              "&:hover": {
+                color: "var(--color-primary-dark)",
+              },
+            },
+            code: {
+              backgroundColor: "var(--color-code-inline-bg)",
+              color: "var(--color-code-inline-text)",
+              borderRadius: "0.25rem",
+              padding: "0.125rem 0.375rem",
+              fontWeight: "400",
+            },
+            "code::before": {
+              content: '""',
+            },
+            "code::after": {
+              content: '""',
+            },
+          },
+        },
+      },
+    },
+  },
+  plugins: [],
+};

package/src/engine/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+    "types": ["node"]
+  },
+  "include": ["src/**/*", "*.ts", "*.mjs"],
+  "exclude": ["node_modules"]
+}

package/src/templates/api-reference.mdx

@@ -0,0 +1,308 @@
+---
+title: API Reference
+description: Example API documentation structure
+---
+
+# API Reference
+
+This is an example of how to structure API documentation with opendocs.
+
+## Authentication
+
+All API requests require authentication using an API key in the header:
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_KEY" \
+  https://api.example.com/v1/users
+```
+
+<Callout type="warning">
+  Never expose your API key in client-side code. Always make API calls from your server.
+</Callout>
+
+## Base URL
+
+All API endpoints use the following base URL:
+
+```
+https://api.example.com/v1
+```
+
+## Endpoints
+
+### List Users
+
+Retrieve a paginated list of users.
+
+```
+GET /users
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | integer | 1 | Page number |
+| `limit` | integer | 20 | Items per page (max: 100) |
+| `sort` | string | `created_at` | Sort field |
+| `order` | string | `desc` | Sort order (`asc` or `desc`) |
+
+**Example Request:**
+
+<CodeGroup>
+```bash cURL
+curl -X GET "https://api.example.com/v1/users?page=1&limit=10" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+```javascript JavaScript
+const response = await fetch('https://api.example.com/v1/users?page=1&limit=10', {
+  headers: {
+    'Authorization': 'Bearer YOUR_API_KEY'
+  }
+});
+const data = await response.json();
+```
+
+```python Python
+import requests
+
+response = requests.get(
+    'https://api.example.com/v1/users',
+    params={'page': 1, 'limit': 10},
+    headers={'Authorization': 'Bearer YOUR_API_KEY'}
+)
+data = response.json()
+```
+</CodeGroup>
+
+**Example Response:**
+
+```json
+{
+  "data": [
+    {
+      "id": "usr_123",
+      "email": "john@example.com",
+      "name": "John Doe",
+      "created_at": "2024-01-15T10:30:00Z"
+    },
+    {
+      "id": "usr_456",
+      "email": "jane@example.com",
+      "name": "Jane Smith",
+      "created_at": "2024-01-14T08:15:00Z"
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 10,
+    "total": 42,
+    "total_pages": 5
+  }
+}
+```
+
+---
+
+### Get User
+
+Retrieve a single user by ID.
+
+```
+GET /users/:id
+```
+
+**Path Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | The user ID |
+
+**Example Request:**
+
+<CodeGroup>
+```bash cURL
+curl -X GET "https://api.example.com/v1/users/usr_123" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+```javascript JavaScript
+const response = await fetch('https://api.example.com/v1/users/usr_123', {
+  headers: {
+    'Authorization': 'Bearer YOUR_API_KEY'
+  }
+});
+const user = await response.json();
+```
+
+```python Python
+import requests
+
+response = requests.get(
+    'https://api.example.com/v1/users/usr_123',
+    headers={'Authorization': 'Bearer YOUR_API_KEY'}
+)
+user = response.json()
+```
+</CodeGroup>
+
+**Example Response:**
+
+```json
+{
+  "id": "usr_123",
+  "email": "john@example.com",
+  "name": "John Doe",
+  "avatar_url": "https://example.com/avatars/john.jpg",
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-20T14:45:00Z"
+}
+```
+
+---
+
+### Create User
+
+Create a new user.
+
+```
+POST /users
+```
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | string | Yes | User's email address |
+| `name` | string | Yes | User's full name |
+| `password` | string | Yes | Password (min 8 characters) |
+
+**Example Request:**
+
+<CodeGroup>
+```bash cURL
+curl -X POST "https://api.example.com/v1/users" \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "new@example.com",
+    "name": "New User",
+    "password": "securepassword123"
+  }'
+```
+
+```javascript JavaScript
+const response = await fetch('https://api.example.com/v1/users', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer YOUR_API_KEY',
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    email: 'new@example.com',
+    name: 'New User',
+    password: 'securepassword123'
+  })
+});
+const user = await response.json();
+```
+
+```python Python
+import requests
+
+response = requests.post(
+    'https://api.example.com/v1/users',
+    headers={
+        'Authorization': 'Bearer YOUR_API_KEY',
+        'Content-Type': 'application/json'
+    },
+    json={
+        'email': 'new@example.com',
+        'name': 'New User',
+        'password': 'securepassword123'
+    }
+)
+user = response.json()
+```
+</CodeGroup>
+
+**Example Response:**
+
+```json
+{
+  "id": "usr_789",
+  "email": "new@example.com",
+  "name": "New User",
+  "created_at": "2024-01-21T16:00:00Z"
+}
+```
+
+---
+
+### Delete User
+
+Delete a user by ID.
+
+```
+DELETE /users/:id
+```
+
+<Callout type="error">
+  This action is irreversible. All user data will be permanently deleted.
+</Callout>
+
+**Example Request:**
+
+```bash
+curl -X DELETE "https://api.example.com/v1/users/usr_123" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+**Response:** `204 No Content`
+
+## Error Handling
+
+The API returns standard HTTP status codes and JSON error responses.
+
+**Error Response Format:**
+
+```json
+{
+  "error": {
+    "code": "invalid_request",
+    "message": "The email field is required.",
+    "field": "email"
+  }
+}
+```
+
+### Status Codes
+
+| Code | Description |
+|------|-------------|
+| `200` | Success |
+| `201` | Created |
+| `204` | No Content |
+| `400` | Bad Request - Invalid parameters |
+| `401` | Unauthorized - Invalid or missing API key |
+| `403` | Forbidden - Insufficient permissions |
+| `404` | Not Found - Resource doesn't exist |
+| `429` | Too Many Requests - Rate limit exceeded |
+| `500` | Internal Server Error |
+
+## Rate Limiting
+
+API requests are limited to **100 requests per minute** per API key.
+
+Rate limit headers are included in all responses:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1705849200
+```
+
+<Callout type="tip">
+  If you need higher rate limits, contact support to discuss enterprise options.
+</Callout>

package/src/templates/components.mdx

@@ -0,0 +1,286 @@
+---
+title: Components
+description: Built-in MDX components to enhance your documentation
+---
+
+# Components
+
+opendocs includes several built-in components to create rich, interactive documentation.
+
+## Callout
+
+Use callouts to highlight important information, warnings, tips, or errors.
+
+<Callout type="info">
+
+This is an **info** callout. Use it for general information and notes.
+
+</Callout>
+
+<Callout type="tip">
+
+This is a **tip** callout. Use it for helpful suggestions and best practices.
+
+</Callout>
+
+<Callout type="warning">
+
+This is a **warning** callout. Use it to caution readers about potential issues.
+
+</Callout>
+
+<Callout type="error">
+
+This is an **error** callout. Use it for critical information or common mistakes.
+
+</Callout>
+
+```mdx
+<Callout type="info">
+  Your message here. Supports **markdown** formatting.
+</Callout>
+```
+
+### Callout Types
+
+| Type | Usage |
+|------|-------|
+| `info` | General information (default) |
+| `tip` | Helpful suggestions |
+| `warning` | Cautions and potential issues |
+| `error` | Critical warnings or common mistakes |
+
+## Code Groups
+
+Display code examples in multiple languages or package managers with tabs.
+
+<CodeGroup>
+```javascript JavaScript
+const greeting = "Hello, World!";
+console.log(greeting);
+```
+
+```python Python
+greeting = "Hello, World!"
+print(greeting)
+```
+
+```rust Rust
+fn main() {
+    println!("Hello, World!");
+}
+```
+</CodeGroup>
+
+````mdx
+<CodeGroup>
+```javascript JavaScript
+const greeting = "Hello, World!";
+```
+
+```python Python
+greeting = "Hello, World!"
+```
+</CodeGroup>
+````
+
+## Cards
+
+Use cards to create navigation links or highlight features.
+
+<CardGroup cols={2}>
+  <Card title="Getting Started" description="Learn the basics of opendocs" href="/quickstart" icon="🚀" />
+  <Card title="Configuration" description="Customize your documentation site" href="/configuration" icon="⚙️" />
+  <Card title="Components" description="Explore built-in MDX components" href="/components" icon="🧩" />
+  <Card title="Writing Content" description="Learn how to write effective docs" href="/writing-content" icon="✍️" />
+</CardGroup>
+
+```mdx
+<CardGroup cols={2}>
+  <Card
+    title="Getting Started"
+    description="Learn the basics"
+    href="/quickstart"
+    icon="🚀"
+  />
+  <Card
+    title="Configuration"
+    description="Customize your site"
+    href="/configuration"
+    icon="⚙️"
+  />
+</CardGroup>
+```
+
+### Card Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | string | Card title (required) |
+| `description` | string | Short description |
+| `href` | string | Link destination |
+| `icon` | string | Emoji or icon character |
+
+### CardGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `cols` | 1, 2, 3, 4 | 2 | Number of columns |
+
+## Steps
+
+Create numbered step-by-step instructions.
+
+<Steps>
+
+### Install the CLI
+
+Install opendocs globally using npm, yarn, or pnpm.
+
+### Initialize your project
+
+Run `opendocs init my-docs` to create a new documentation project.
+
+### Start the dev server
+
+Run `opendocs dev` to preview your documentation locally.
+
+### Deploy
+
+Build and deploy your documentation to any static hosting service.
+
+</Steps>
+
+```mdx
+<Steps>
+
+### Step One
+
+Description for step one.
+
+### Step Two
+
+Description for step two.
+
+### Step Three
+
+Description for step three.
+
+</Steps>
+```
+
+<Callout type="tip">
+
+Steps automatically number each child heading (h3, h4, etc.) and display them with a connected timeline.
+
+</Callout>
+
+## Combining Components
+
+Components can be nested and combined for more complex layouts.
+
+### Steps with Cards
+
+Use Cards inside Steps to provide navigation options at each stage:
+
+<Steps>
+
+### Choose your setup
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" description="Get running in minutes" href="/quickstart" icon="⚡" />
+  <Card title="Manual Setup" description="Full control over configuration" href="/configuration" icon="🔧" />
+</CardGroup>
+
+### Configure your project
+
+<Callout type="info">
+
+Edit `docs.json` to customize navigation, theme, and features.
+
+</Callout>
+
+### Write your content
+
+Create `.mdx` files and start documenting your project.
+
+</Steps>
+
+### Cards with Code Examples
+
+Combine explanatory cards with code samples:
+
+<CardGroup cols={2}>
+  <Card title="Frontend" description="React, Vue, or vanilla JS" icon="🖥️" />
+  <Card title="Backend" description="Node.js, Python, or Go" icon="⚙️" />
+</CardGroup>
+
+<CodeGroup>
+```javascript React
+import { useState } from 'react';
+
+function App() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+
+```python FastAPI
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/")
+def read_root():
+    return {"Hello": "World"}
+```
+</CodeGroup>
+
+### Callouts in Context
+
+Use callouts within other components to highlight important information:
+
+<Steps>
+
+### Install dependencies
+
+```bash
+pnpm install
+```
+
+<Callout type="warning">
+
+Make sure you have Node.js 18+ installed before proceeding.
+
+</Callout>
+
+### Start development
+
+```bash
+pnpm dev
+```
+
+<Callout type="tip">
+
+The dev server supports hot reload - changes appear instantly!
+
+</Callout>
+
+</Steps>
+
+### Feature Comparison Tables
+
+Combine tables with callouts for feature documentation:
+
+| Feature | Free | Pro | Enterprise |
+|---------|------|-----|------------|
+| Pages | 10 | 100 | Unlimited |
+| Custom domain | No | Yes | Yes |
+| Analytics | Basic | Advanced | Advanced |
+| Support | Community | Email | Dedicated |
+
+<Callout type="info">
+
+All plans include search, dark mode, and responsive design.
+
+</Callout>