@opendocsdev/cli 0.2.0

package/README.md

@@ -0,0 +1,300 @@
+# opendocs
+
+[![npm version](https://img.shields.io/npm/v/opendocs.svg)](https://www.npmjs.com/package/opendocs)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://github.com/chigala/opendocs/blob/main/LICENSE)
+
+Beautiful docs with zero config. An open-source alternative to [Mintlify](https://mintlify.com).
+
+Write documentation in MDX, get built-in search, syntax highlighting, theming, and deploy anywhere.
+
+## Installation
+
+```bash
+npm install -g opendocs
+```
+
+Or use directly with npx:
+
+```bash
+npx opendocs init my-docs
+```
+
+## Commands
+
+### `opendocs init [name]`
+
+Scaffold a new documentation project.
+
+```bash
+opendocs init my-docs
+```
+
+Creates a directory with a starter `docs.json`, example MDX pages, and a `public/` folder for static assets.
+
+### `opendocs dev`
+
+Start a local development server with hot reload.
+
+```bash
+opendocs dev
+opendocs dev --port 3000
+```
+
+### `opendocs build`
+
+Build the documentation site for production. Outputs static HTML to `dist/`.
+
+```bash
+opendocs build
+```
+
+### `opendocs preview`
+
+Preview the production build locally.
+
+```bash
+opendocs preview
+opendocs preview --port 3000
+```
+
+### `opendocs deploy`
+
+Deploy docs to the hosted platform.
+
+```bash
+opendocs deploy
+opendocs deploy --skip-build  # Use existing dist/
+```
+
+Requires `OPENDOCS_API_KEY` and `OPENDOCS_SITE_ID` environment variables (or configure in `docs.json`).
+
+## Configuration
+
+All configuration lives in `docs.json` at the project root.
+
+```json
+{
+  "name": "My Docs",
+  "logo": {
+    "light": "/logo.svg",
+    "dark": "/logo-dark.svg"
+  },
+  "favicon": "/favicon.svg",
+  "navigation": [
+    {
+      "group": "Getting Started",
+      "pages": ["introduction", "quickstart"]
+    },
+    {
+      "group": "Guides",
+      "pages": [
+        "components",
+        {
+          "group": "Advanced",
+          "pages": ["custom-components", "theming"]
+        }
+      ]
+    }
+  ],
+  "theme": {
+    "primaryColor": "#10b981",
+    "accentColor": "#8b5cf6",
+    "darkMode": true
+  },
+  "features": {
+    "search": true,
+    "feedback": true,
+    "analytics": true
+  },
+  "snippets": ["snippets"],
+  "backend": {
+    "siteId": "your-site-id",
+    "apiUrl": "https://app.opendocs.dev"
+  },
+  "metadata": {
+    "url": "https://docs.example.com",
+    "ogImage": "/og-image.png"
+  }
+}
+```
+
+### Navigation
+
+Navigation supports flat pages and nested groups:
+
+```json
+{
+  "navigation": [
+    {
+      "group": "Group Name",
+      "pages": [
+        "page-slug",
+        {
+          "group": "Nested Group",
+          "pages": ["nested/page-one", "nested/page-two"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Page slugs map to MDX files relative to the project root (e.g., `"quickstart"` maps to `quickstart.mdx`).
+
+### Snippets
+
+Reusable MDX content that can be imported across pages:
+
+```json
+{
+  "snippets": ["snippets"]
+}
+```
+
+Place `.mdx` files in the `snippets/` directory and import them in any page.
+
+## Built-in Components
+
+All components are available in MDX files without imports.
+
+### Callout
+
+```mdx
+<Callout type="info" title="Note">
+  This is an informational callout.
+</Callout>
+```
+
+Types: `info`, `warning`, `error`, `tip`
+
+### Card
+
+```mdx
+<Card title="Getting Started" href="/quickstart">
+  Learn how to set up your docs in minutes.
+</Card>
+```
+
+### CardGroup
+
+```mdx
+<CardGroup cols={2}>
+  <Card title="First" href="/first">Description</Card>
+  <Card title="Second" href="/second">Description</Card>
+</CardGroup>
+```
+
+### CodeGroup
+
+Tabbed code blocks for showing the same example in multiple languages:
+
+````mdx
+<CodeGroup>
+```bash npm
+npm install opendocs
+```
+
+```bash pnpm
+pnpm add opendocs
+```
+
+```bash yarn
+yarn add opendocs
+```
+</CodeGroup>
+````
+
+### Tabs / Tab
+
+```mdx
+<Tabs>
+  <Tab title="React">
+    React content here.
+  </Tab>
+  <Tab title="Vue">
+    Vue content here.
+  </Tab>
+</Tabs>
+```
+
+### Steps
+
+```mdx
+<Steps>
+  ### Install the CLI
+
+  Run `npm install -g opendocs`.
+
+  ### Create a project
+
+  Run `opendocs init my-docs`.
+
+  ### Start writing
+
+  Edit the MDX files in your project.
+</Steps>
+```
+
+### ApiPlayground
+
+Interactive API endpoint explorer:
+
+```mdx
+<ApiPlayground
+  method="GET"
+  endpoint="/api/users"
+  description="List all users"
+/>
+```
+
+## Theming
+
+Colors are configured in `docs.json` and support both light and dark mode:
+
+```json
+{
+  "theme": {
+    "primaryColor": "#10b981",
+    "accentColor": "#8b5cf6",
+    "darkMode": true
+  }
+}
+```
+
+The engine automatically generates light/dark variants from your chosen colors.
+
+## Tech Stack
+
+- [Astro](https://astro.build/) — Static site generation
+- [Tailwind CSS](https://tailwindcss.com/) — Styling
+- [Shiki](https://shiki.style/) — Syntax highlighting
+- [Pagefind](https://pagefind.app/) — Client-side search
+- [MDX](https://mdxjs.com/) — Markdown with JSX components
+
+## Development
+
+```bash
+cd packages/cli
+
+# Run tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+
+# Type check
+pnpm typecheck
+
+# Build
+pnpm build
+```
+
+The Astro engine source is at `src/engine/` and is separate from the CLI's tsconfig.
+
+## Self-Hosting
+
+opendocs also includes a server with analytics, a management dashboard, and edge serving. See the [full repository](https://github.com/chigala/opendocs) for self-hosting instructions.
+
+## License
+
+[AGPL-3.0](https://github.com/chigala/opendocs/blob/main/LICENSE)