{"id":30062522,"url":"https://github.com/ericc-ch/opencode-serve","last_synced_at":"2025-08-08T03:36:47.407Z","repository":{"id":308302567,"uuid":"1032327260","full_name":"ericc-ch/opencode-serve","owner":"ericc-ch","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-05T08:22:20.000Z","size":77,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-05T08:38:51.754Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ericc-ch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-05T06:37:05.000Z","updated_at":"2025-08-05T08:22:23.000Z","dependencies_parsed_at":"2025-08-05T08:53:05.041Z","dependency_job_id":null,"html_url":"https://github.com/ericc-ch/opencode-serve","commit_stats":null,"previous_names":["ericc-ch/opencode-serve"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ericc-ch/opencode-serve","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericc-ch%2Fopencode-serve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericc-ch%2Fopencode-serve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericc-ch%2Fopencode-serve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericc-ch%2Fopencode-serve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericc-ch","download_url":"https://codeload.github.com/ericc-ch/opencode-serve/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericc-ch%2Fopencode-serve/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269360652,"owners_count":24404295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-08T03:36:44.677Z","updated_at":"2025-08-08T03:36:47.393Z","avatar_url":"https://github.com/ericc-ch.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opencode Documentation Site\n\nA beautiful static site generator for Markdown documentation built with React, Bun, and Tailwind CSS. Transform your `docs/` folder into a professional documentation website with automatic navigation, syntax highlighting, and responsive design.\n\n## ✨ Features\n\n- 📝 **Markdown Support**: Full GitHub Flavored Markdown (GFM) support with tables, task lists, footnotes\n- 🎨 **Syntax Highlighting**: Beautiful code highlighting with Prism.js (supports 100+ languages)\n- 🔍 **Full-Text Search**: Powered by Pagefind with instant, low-bandwidth search\n- 🎯 **Static Generation**: Fast, SEO-friendly static HTML pages (no JavaScript runtime needed)\n- 📱 **Responsive Design**: Mobile-first design with Tailwind CSS\n- 🧭 **Auto Navigation**: Automatic sidebar navigation generation from file structure\n- 🏷️ **SEO Optimized**: Complete metadata, Open Graph tags, and structured data\n- ⚡ **Fast**: Built with Bun for optimal performance and instant rebuilds\n- 🧪 **Tested**: Comprehensive Playwright integration tests\n- 🎭 **shadcn/ui Ready**: Integrated with shadcn/ui components for consistent design\n\n## 🚀 Quick Start\n\n### 1. Install Dependencies\n\n```bash\nbun install\n```\n\n### 2. Build the Documentation Site\n\n```bash\nbun run build:docs\n```\n\nThis command will:\n- 🔍 Automatically discover all `.md` files in the `docs/` directory  \n- 🎨 Process them with syntax highlighting and GFM features\n- 📄 Generate static HTML pages with navigation\n- 🔎 Create a full-text search index with Pagefind\n- 📁 Output everything to the `dist/` directory\n- ✅ Generate **9 pages total** (1 homepage + 8 documentation pages)\n\n### 3. Serve the Site Locally\n\n```bash\nbun run serve:docs\n```\n\n🌐 Visit `http://localhost:3000` to view your documentation site.\n\n### 4. Run Integration Tests\n\n```bash\nbun test\n```\n\nRuns comprehensive Playwright tests covering navigation, rendering, and responsive design.\n\n## 📁 Project Structure\n\n```\n├── docs/                    # 📝 Markdown documentation files\n│   ├── api-reference.md     # Main API documentation  \n│   ├── sessions.md          # Sessions API\n│   ├── app.md              # App API\n│   ├── config.md           # Config API\n│   ├── events.md           # Events API\n│   ├── find.md             # Find API\n│   ├── file-mode-log.md    # File API\n│   ├── schemas.md          # API Schemas\n│   └── opencode-openapi.json # OpenAPI specification\n├── src/\n│   ├── ssg.tsx             # 🏗️ Static Site Generator core\n│   ├── server.tsx          # 🌐 Development server\n│   └── components/         # 🧩 React components (shadcn/ui)\n├── tests/\n│   └── docs.spec.ts        # 🧪 Playwright integration tests\n├── dist/                   # 📦 Generated static site (deployable)\n│   ├── index.html          # Homepage with doc cards\n│   ├── api-reference/      # Individual doc pages\n│   ├── sessions/\n│   └── ...\n└── playwright.config.ts    # ⚙️ Test configuration\n```\n\n## 🎯 How It Works\n\nThe SSG follows a simple 3-step process:\n\n1. **🔍 Discovery**: Scans the `docs/` directory for `.md` files automatically\n2. **⚙️ Processing**: Each Markdown file is enhanced with:\n   - `react-markdown` for React-based rendering\n   - `remark-gfm` for GitHub Flavored Markdown features\n   - `react-syntax-highlighter` with Prism.js for beautiful code highlighting\n3. **📦 Generation**: Creates static HTML pages featuring:\n   - Fixed sidebar navigation with automatic links\n   - Responsive Tailwind CSS layout\n   - SEO-friendly meta tags and structure\n   - Clean URLs (`/api-reference/` instead of `/api-reference.html`)\n\n### ✨ Current Documentation\n\nThe SSG has successfully processed **8 documentation files**:\n\n| File | Title | Generated URL |\n|------|-------|---------------|\n| `api-reference.md` | opencode API Reference | `/api-reference/` |\n| `sessions.md` | Sessions API | `/sessions/` |\n| `app.md` | App API | `/app/` |\n| `config.md` | Config API | `/config/` |\n| `events.md` | Events API | `/events/` |\n| `find.md` | Find API | `/find/` |\n| `file-mode-log.md` | File API | `/file-mode-log/` |\n| `schemas.md` | API Schemas | `/schemas/` |\n\n## 📝 Writing Documentation\n\n### File Structure\n\nPlace your `.md` files in the `docs/` directory. The SSG will:\n- Use the first `# Heading` as the page title\n- Generate a URL slug from the filename\n- Create navigation automatically\n\n### Supported Markdown Features\n\n- ✅ Headers (`# ## ###`)\n- ✅ **Bold** and *italic* text  \n- ✅ `inline code` and code blocks\n- ✅ Tables\n- ✅ Lists (ordered and unordered)\n- ✅ Links and images\n- ✅ Blockquotes\n- ✅ Strikethrough (`~~text~~`)\n- ✅ Task lists (`- [x] Done`)\n- ✅ Footnotes\n\n### Code Highlighting\n\nThe SSG supports syntax highlighting for 100+ programming languages. Specify the language for optimal highlighting:\n\n````markdown\n```javascript\nconst events = new EventSource(\"http://localhost:8080/event\");\nevents.onmessage = (e) =\u003e console.log(JSON.parse(e.data));\n```\n\n```bash\ncurl -X POST http://localhost:8080/session \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"providerID\": \"anthropic\", \"modelID\": \"claude-3-sonnet\"}'\n```\n\n```typescript\ninterface SessionResponse {\n  id: string;\n  status: 'active' | 'inactive';\n}\n```\n````\n\n**Supported languages include**: JavaScript, TypeScript, Python, Bash, JSON, YAML, SQL, Go, Rust, and many more.\n\n## 🎨 Styling\n\nThe site uses Tailwind CSS for styling with:\n- Clean, professional design\n- Dark syntax highlighting theme\n- Responsive layout\n- Accessibility-friendly colors\n\n## 🛠 Development\n\n### Available Scripts\n\n| Command | Description |\n|---------|-------------|\n| `bun run build:docs` | 🏗️ Generate the complete static site |\n| `bun run serve:docs` | 🌐 Serve the site locally on port 3000 |\n| `bun test` | 🧪 Run comprehensive Playwright tests |\n| `bun run dev` | ⚡ Development mode for the main app |\n\n### Customization Options\n\n#### 🎨 Site Configuration\n\nEdit the main configuration in `src/ssg.tsx`:\n\n```typescript\nconst ssg = new StaticSiteGenerator(\n  'docs',                    // Source directory\n  'dist',                    // Output directory  \n  {\n    title: 'opencode Documentation',           // Site title\n    description: 'Comprehensive documentation for opencode'  // SEO description\n  }\n);\n```\n\n#### 🎭 Styling \u0026 Theme\n\n**Tailwind CSS Classes**: Modify styling directly in `src/ssg.tsx`:\n- Navigation: `bg-white border-r border-gray-200 w-64 fixed`\n- Content: `bg-white rounded-lg shadow-sm p-8`\n- Typography: `text-3xl font-bold text-gray-900`\n\n**Syntax Highlighting Theme**: Change the imported theme:\n```typescript\nimport { oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism';\n// Or try: vs, tomorrow, okaidia, funky, etc.\n```\n\n**Custom CSS**: Add styles in the `\u003cstyle\u003e` section of the layout component.\n\n## 🧪 Testing\n\nThe project includes a comprehensive Playwright test suite that validates:\n\n- ✅ **Homepage functionality**: Navigation cards, titles, descriptions\n- ✅ **Individual page rendering**: All 8 documentation pages load correctly  \n- ✅ **Navigation system**: Sidebar links work, home button functions\n- ✅ **Syntax highlighting**: Code blocks render with proper styling\n- ✅ **Responsive design**: Mobile and desktop layouts work\n- ✅ **SEO elements**: Meta tags, titles, and structure are correct\n- ✅ **Link integrity**: All internal links function properly\n\n### Running Tests\n\n```bash\n# Run all tests\nbun test\n\n# Run tests in headed mode (see browser)\nbunx playwright test --headed\n\n# Run specific test file\nbunx playwright test tests/docs.spec.ts\n```\n\n## 📦 Technology Stack\n\n### Core Dependencies\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `react` | ^19 | UI framework for component rendering |\n| `react-markdown` | ^10.1.0 | Markdown to React component conversion |\n| `remark-gfm` | ^4.0.1 | GitHub Flavored Markdown support |\n| `react-syntax-highlighter` | ^15.6.1 | Prism.js code highlighting for React |\n\n### Development \u0026 Build Tools\n| Package | Purpose |\n|---------|---------|\n| `bun` | Runtime, package manager, and build tool |\n| `playwright` | End-to-end testing framework |\n| `tailwindcss` | Utility-first CSS framework |\n| `@types/react-syntax-highlighter` | TypeScript definitions |\n\n### UI \u0026 Styling\n- **Tailwind CSS**: Utility-first styling with responsive design\n- **shadcn/ui**: Pre-built accessible components\n- **Prism.js**: Syntax highlighting with oneDark theme\n- **Custom components**: Button, Card, Form, Input, Label, Select\n\n## 🚢 Deployment\n\nThe `dist/` directory contains fully static files ready for deployment to any hosting service:\n\n### 🔥 Recommended Hosting Options\n\n| Platform | Setup | Benefits |\n|----------|--------|----------|\n| **Netlify** | Drag \u0026 drop `dist/` folder | ✅ Instant deploy, CDN, branch previews |\n| **Vercel** | Connect GitHub repo | ✅ Git integration, edge functions, analytics |\n| **GitHub Pages** | Upload to `gh-pages` branch | ✅ Free, git-integrated, custom domains |\n| **Cloudflare Pages** | Connect repository | ✅ Global CDN, fast builds, edge workers |\n\n### 📁 Deployment Files\n\nThe generated `dist/` directory structure:\n```\ndist/\n├── index.html              # Homepage with navigation cards\n├── api-reference/\n│   └── index.html         # Clean URLs (no .html extension needed)\n├── sessions/\n│   └── index.html\n└── ... (all other doc pages)\n```\n\n### ⚡ Performance Features\n\n- **Static HTML**: No JavaScript runtime required\n- **Clean URLs**: SEO-friendly paths like `/api-reference/`\n- **Optimized CSS**: Tailwind CSS loaded via CDN\n- **Fast Loading**: Minimal HTML with embedded styles\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n---\n\n## 🎯 Results Summary\n\n✅ **Successfully generated a complete documentation site with:**\n\n- 🏠 **1 Homepage** with navigation cards for all documentation\n- 📄 **8 Documentation pages** rendered from Markdown with full GFM support\n- 🎨 **Beautiful syntax highlighting** for code blocks in multiple languages  \n- 📱 **Responsive design** that works on all devices\n- 🧪 **Comprehensive test suite** covering all functionality\n- ⚡ **Fast static generation** with Bun and React\n- 🔍 **SEO-optimized** HTML with proper meta tags and structure\n\n**📊 Total Output**: 9 HTML pages ready for deployment\n\n**🚀 Ready to deploy**: Upload the `dist/` folder to any static hosting service!\n\n---\n\n**Built with ❤️ using Bun, React, Tailwind CSS, and shadcn/ui**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericc-ch%2Fopencode-serve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericc-ch%2Fopencode-serve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericc-ch%2Fopencode-serve/lists"}