@opendocsdev/cli 0.2.0

package/dist/templates/writing-content.mdx

@@ -0,0 +1,236 @@
+---
+title: Writing Content
+description: Learn how to write effective documentation with MDX
+---
+
+# Writing Content
+
+opendocs uses MDX, which combines Markdown with JSX components for rich documentation.
+
+## Frontmatter
+
+Every page should start with frontmatter that defines metadata:
+
+```mdx
+---
+title: Page Title
+description: A brief description for SEO and previews
+---
+
+# Your Content Here
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Page title (shown in browser tab and navigation) |
+| `description` | No | Short description for SEO and social sharing |
+
+## Markdown Basics
+
+opendocs supports all standard Markdown syntax.
+
+### Headings
+
+```markdown
+# Heading 1
+## Heading 2
+### Heading 3
+#### Heading 4
+```
+
+<Callout type="tip">
+  Use `##` (H2) for main sections. These appear in the "On this page" table of contents.
+</Callout>
+
+### Text Formatting
+
+| Syntax | Result |
+|--------|--------|
+| `**bold**` | **bold** |
+| `*italic*` | *italic* |
+| `~~strikethrough~~` | ~~strikethrough~~ |
+| `` `inline code` `` | `inline code` |
+
+### Lists
+
+**Unordered lists:**
+
+```markdown
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+```
+
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+
+**Ordered lists:**
+
+```markdown
+1. First step
+2. Second step
+3. Third step
+```
+
+1. First step
+2. Second step
+3. Third step
+
+### Links
+
+```markdown
+[Link text](https://example.com)
+[Internal link](/quickstart)
+```
+
+[Link text](https://example.com) | [Internal link](/quickstart)
+
+### Images
+
+Place images in the `public` directory and reference them:
+
+```markdown
+![Alt text](/images/screenshot.png)
+```
+
+### Tables
+
+```markdown
+| Header 1 | Header 2 | Header 3 |
+|----------|----------|----------|
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+```
+
+| Header 1 | Header 2 | Header 3 |
+|----------|----------|----------|
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+
+### Blockquotes
+
+```markdown
+> This is a blockquote. Use it to highlight quotes or important notes.
+```
+
+> This is a blockquote. Use it to highlight quotes or important notes.
+
+## Code Blocks
+
+### Basic Code Blocks
+
+Use triple backticks with a language identifier:
+
+```javascript
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+```javascript
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+### Supported Languages
+
+opendocs supports syntax highlighting for 100+ languages including:
+
+- JavaScript, TypeScript, JSX, TSX
+- Python, Ruby, Go, Rust
+- HTML, CSS, SCSS
+- JSON, YAML, TOML
+- Bash, Shell
+- SQL, GraphQL
+- And many more...
+
+### Code Groups for Multiple Languages
+
+Use the `CodeGroup` component to show code in multiple languages:
+
+<CodeGroup>
+```javascript Node.js
+const express = require('express');
+const app = express();
+
+app.get('/', (req, res) => {
+  res.send('Hello World!');
+});
+```
+
+```python Flask
+from flask import Flask
+app = Flask(__name__)
+
+@app.route('/')
+def hello():
+    return 'Hello World!'
+```
+
+```go Go
+package main
+
+import "net/http"
+
+func main() {
+    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+        w.Write([]byte("Hello World!"))
+    })
+    http.ListenAndServe(":8080", nil)
+}
+```
+</CodeGroup>
+
+## Using Components
+
+Import and use built-in components directly in your MDX:
+
+```mdx
+<Callout type="info">
+  This is an informational callout.
+</Callout>
+
+<CardGroup cols={2}>
+  <Card title="Card 1" description="Description" href="/page1" />
+  <Card title="Card 2" description="Description" href="/page2" />
+</CardGroup>
+```
+
+See the [Components](/components) page for all available components.
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card
+    title="Keep it concise"
+    description="Write short paragraphs. Use lists and tables for clarity."
+    icon="✂️"
+  />
+  <Card
+    title="Use examples"
+    description="Show, don't tell. Include code samples and screenshots."
+    icon="💻"
+  />
+  <Card
+    title="Structure content"
+    description="Use headings to create a clear hierarchy."
+    icon="📋"
+  />
+  <Card
+    title="Add callouts"
+    description="Highlight important info, warnings, and tips."
+    icon="💡"
+  />
+</CardGroup>
+
+<Callout type="tip">
+  Write documentation as if the reader is in a hurry. Get to the point quickly and make information easy to scan.
+</Callout>

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@opendocsdev/cli",
+  "version": "0.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Beautiful docs with zero config. Open-source Mintlify alternative.",
+  "license": "AGPL-3.0",
+  "author": "Chigala",
+  "homepage": "https://github.com/chigala/opendocs#readme",
+  "bugs": {
+    "url": "https://github.com/chigala/opendocs/issues"
+  },
+  "keywords": [
+    "documentation",
+    "docs",
+    "mdx",
+    "astro",
+    "cli",
+    "static-site",
+    "mintlify",
+    "opendocs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chigala/opendocs.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "type": "module",
+  "bin": {
+    "opendocs": "./dist/bin/opendocs.js"
+  },
+  "files": [
+    "dist",
+    "src/engine/astro.config.ts",
+    "src/engine/tailwind.config.mjs",
+    "src/engine/tsconfig.json",
+    "src/engine/src",
+    "src/templates"
+  ],
+  "dependencies": {
+    "@astrojs/mdx": "^3.1.0",
+    "@astrojs/react": "^4.4.2",
+    "@astrojs/tailwind": "^5.1.0",
+    "@fontsource-variable/geist": "^5.2.8",
+    "@fontsource-variable/geist-mono": "^5.2.7",
+    "@inquirer/prompts": "^8.2.0",
+    "@lucide/astro": "^0.563.0",
+    "@mdx-js/mdx": "^3.1.1",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "astro": "^4.16.0",
+    "chalk": "^5.3.0",
+    "clsx": "^2.0.0",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.2",
+    "fs-extra": "^11.2.0",
+    "lucide-react": "^0.563.0",
+    "ora": "^8.1.1",
+    "pagefind": "^1.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rehype-shiki": "^0.0.9",
+    "rehype-stringify": "^10.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "shiki": "^1.29.2",
+    "tailwind-merge": "^3.4.0",
+    "tar-stream": "^3.1.7",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.0.0",
+    "@types/tar-stream": "^3.1.4",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.0",
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/engine/astro.config.ts

@@ -0,0 +1,75 @@
+import { defineConfig } from "astro/config";
+import mdx from "@astrojs/mdx";
+import tailwind from "@astrojs/tailwind";
+import react from "@astrojs/react";
+import remarkGfm from "remark-gfm";
+import { remarkOpendocs } from "./src/lib/remark-opendocs";
+import path from "node:path";
+import type { ShikiTransformer } from "shiki";
+
+// Get the user's project directory from environment variable
+const projectDir = process.env.OPENDOCS_PROJECT_DIR || process.cwd();
+
+// Get the engine directory (where this config file lives)
+const engineDir = new URL(".", import.meta.url).pathname;
+
+// Custom Shiki transformer to expose meta string as data-title attribute
+// This allows CodeGroup to extract tab labels from code fences like: ```bash npm
+const metaTransformer: ShikiTransformer = {
+  name: "meta-to-data-title",
+  pre(node) {
+    const meta = this.options.meta?.__raw;
+    if (meta) {
+      node.properties["data-title"] = meta;
+    }
+  },
+};
+
+export default defineConfig({
+  prefetch: {
+    prefetchAll: true, // Prefetch all links for instant navigation
+  },
+  integrations: [
+    react(),
+    mdx(),
+    tailwind({
+      applyBaseStyles: false,
+    }),
+  ],
+  markdown: {
+    remarkPlugins: [remarkGfm, remarkOpendocs],
+    shikiConfig: {
+      themes: {
+        light: "github-light",
+        dark: "github-dark",
+      },
+      defaultColor: false,
+      langs: [],
+      wrap: true,
+      transformers: [metaTransformer],
+    },
+  },
+  // Allow importing MDX files from the user's project directory
+  vite: {
+    resolve: {
+      alias: [
+        // @content alias points to the user's project directory
+        // Used by mdx-loader.ts to glob all MDX/MD files
+        { find: "@content", replacement: projectDir },
+        {
+          find: "@opendocs/components",
+          replacement: `${engineDir}src/components/react/index.ts`,
+        },
+      ],
+    },
+    server: {
+      watch: {
+        ignored: [`!${projectDir}/**`],
+      },
+    },
+  },
+  // Output directory relative to the engine
+  outDir: path.join(projectDir, "dist"),
+  // Serve content from the user's project directory
+  publicDir: path.join(projectDir, "public"),
+});

package/src/engine/src/components/Analytics.astro

@@ -0,0 +1,57 @@
+---
+/**
+ * Analytics - Pageview tracking component
+ * Sends analytics to backend if configured in docs.json
+ */
+import { loadConfig } from "../lib/config.js";
+
+interface Props {
+  path?: string;
+}
+
+const { path: propPath } = Astro.props;
+
+// Load config and extract analytics settings
+const config = await loadConfig();
+const backendConfig = config.backend as { apiUrl?: string; siteId?: string } | undefined;
+const backend = backendConfig?.apiUrl;
+const siteId = backendConfig?.siteId;
+const analyticsEnabled = config.features?.analytics !== false;
+
+// Only render script if backend and siteId are configured
+const shouldTrack = backend && siteId && analyticsEnabled;
+---
+
+{shouldTrack && (
+  <script
+    data-backend={backend}
+    data-site-id={siteId}
+    data-path={propPath}
+    is:inline
+  >
+    (function() {
+      // Get configuration from script tag
+      const script = document.currentScript;
+      const backend = script.getAttribute('data-backend');
+      const siteId = script.getAttribute('data-site-id');
+      const pathFromProp = script.getAttribute('data-path');
+
+      // Use provided path or current pathname
+      const path = pathFromProp || window.location.pathname;
+
+      // Send pageview to backend (short path to avoid ad blockers)
+      fetch(`${backend}/api/analytics/pv`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          siteId: siteId,
+          path: path,
+        }),
+      }).catch(function(err) {
+        console.debug('[opendocs] Analytics error:', err);
+      });
+    })();
+  </script>
+)}

package/src/engine/src/components/ApiPlayground.astro

@@ -0,0 +1,24 @@
+---
+import ApiPlaygroundReact from "./react/ApiPlayground/index";
+
+export interface Props {
+  endpoint: string;
+  method: string;
+  baseUrl: string;
+  defaultHeaders?: Record<string, string>;
+  defaultBody?: Record<string, unknown> | string;
+  defaultParams?: Record<string, string>;
+}
+
+const { endpoint, method, baseUrl, defaultHeaders, defaultBody, defaultParams } = Astro.props;
+---
+
+<ApiPlaygroundReact
+  client:load
+  endpoint={endpoint}
+  method={method}
+  baseUrl={baseUrl}
+  defaultHeaders={defaultHeaders}
+  defaultBody={defaultBody}
+  defaultParams={defaultParams}
+/>

package/src/engine/src/components/Callout.astro

@@ -0,0 +1,66 @@
+---
+/**
+ * Callout - Informational alert boxes
+ * Pure Astro component - no client-side JavaScript needed
+ */
+import { Info, AlertTriangle, XCircle, Lightbulb } from '@lucide/astro';
+
+interface Props {
+  type?: "info" | "warning" | "error" | "tip";
+  title?: string;
+  class?: string;
+}
+
+const { type = "info", title, class: className } = Astro.props;
+
+const variants = {
+  info: {
+    border: "border-l-[var(--color-info)]",
+    iconColor: "text-[var(--color-info)]",
+    icon: Info,
+  },
+  warning: {
+    border: "border-l-[var(--color-warning)]",
+    iconColor: "text-[var(--color-warning)]",
+    icon: AlertTriangle,
+  },
+  error: {
+    border: "border-l-[var(--color-error)]",
+    iconColor: "text-[var(--color-error)]",
+    icon: XCircle,
+  },
+  tip: {
+    border: "border-l-[var(--color-success)]",
+    iconColor: "text-[var(--color-success)]",
+    icon: Lightbulb,
+  },
+};
+
+const variant = variants[type] || variants.info;
+const Icon = variant.icon;
+---
+
+<div
+  class:list={[
+    "callout rounded-lg border-l-4 my-6 p-4",
+    "bg-[var(--color-surface-raised)]",
+    variant.border,
+    className,
+  ]}
+  role="alert"
+  data-type={type}
+>
+  <div class="flex gap-3">
+    <span class:list={["flex-shrink-0 mt-0.5", variant.iconColor]}>
+      <Icon class="w-5 h-5" aria-hidden="true" />
+    </span>
+    <div class="flex-1 min-w-0">
+      {title && (
+        <p class="font-semibold text-[var(--color-foreground)] mb-1">{title}</p>
+      )}
+      <div class="callout-content text-[var(--color-muted)] text-sm [&>p]:my-0 [&>p+p]:mt-2 [&>ul]:my-2 [&>ol]:my-2 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0">
+        <slot />
+      </div>
+    </div>
+  </div>
+</div>

package/src/engine/src/components/Card.astro

@@ -0,0 +1,75 @@
+---
+/**
+ * Card - Content card with optional link
+ * Pure Astro component - no client-side JavaScript needed
+ */
+interface Props {
+  title: string;
+  description?: string;
+  href?: string;
+  icon?: string;
+  class?: string;
+}
+
+const { title, description, href, icon, class: className } = Astro.props;
+const isLink = !!href;
+---
+
+{isLink ? (
+  <a
+    href={href}
+    class:list={[
+      "card group block p-6 rounded-xl cursor-pointer no-underline",
+      "bg-[var(--color-surface-raised)]",
+      className,
+    ]}
+  >
+    {icon && (
+      <span
+        class="card-icon flex items-center justify-center w-10 h-10 mb-4 rounded-lg bg-[var(--color-surface-sunken)] text-xl"
+        aria-hidden="true"
+      >
+        {icon}
+      </span>
+    )}
+    <h3 class="card-title text-base font-semibold m-0 text-[var(--color-primary)]">
+      {title}
+    </h3>
+    {description && (
+      <p class="card-description text-sm text-[var(--color-muted)] mt-2 mb-0">
+        {description}
+      </p>
+    )}
+    <div class="card-content text-sm text-[var(--color-muted)] mt-2">
+      <slot />
+    </div>
+  </a>
+) : (
+  <div
+    class:list={[
+      "card group block p-6 rounded-xl",
+      "bg-[var(--color-surface-raised)]",
+      className,
+    ]}
+  >
+    {icon && (
+      <span
+        class="card-icon flex items-center justify-center w-10 h-10 mb-4 rounded-lg bg-[var(--color-surface-sunken)] text-xl"
+        aria-hidden="true"
+      >
+        {icon}
+      </span>
+    )}
+    <h3 class="card-title text-base font-semibold m-0 text-[var(--color-foreground)]">
+      {title}
+    </h3>
+    {description && (
+      <p class="card-description text-sm text-[var(--color-muted)] mt-2 mb-0">
+        {description}
+      </p>
+    )}
+    <div class="card-content text-sm text-[var(--color-muted)] mt-2">
+      <slot />
+    </div>
+  </div>
+)}

package/src/engine/src/components/CardGroup.astro

@@ -0,0 +1,29 @@
+---
+/**
+ * CardGroup - Grid layout for Card components
+ * Pure Astro component - no client-side JavaScript needed
+ */
+interface Props {
+  cols?: 1 | 2 | 3 | 4;
+  class?: string;
+}
+
+const { cols = 2, class: className } = Astro.props;
+
+const colVariants: Record<number, string> = {
+  1: "grid-cols-1",
+  2: "grid-cols-1 sm:grid-cols-2",
+  3: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3",
+  4: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-4",
+};
+---
+
+<div
+  class:list={[
+    "card-group grid gap-4 my-6 not-prose",
+    colVariants[cols],
+    className,
+  ]}
+>
+  <slot />
+</div>