{"id":51940602,"url":"https://github.com/amafjarkasi/zephyr-developer-portal","last_synced_at":"2026-07-28T18:30:37.541Z","repository":{"id":357110964,"uuid":"1235361532","full_name":"amafjarkasi/zephyr-developer-portal","owner":"amafjarkasi","description":"Beautiful, accessible React UI components built with TypeScript, Zudoku, and MDX. Interactive documentation with live examples, API references, and best practices.","archived":false,"fork":false,"pushed_at":"2026-05-12T02:31:11.000Z","size":1822,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-12T04:31:02.662Z","etag":null,"topics":["api-docs","developer-portal","documentation","mdx","openapi","react","typescript","ui-components","zudoku"],"latest_commit_sha":null,"homepage":null,"language":"MDX","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/amafjarkasi.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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-11T08:50:50.000Z","updated_at":"2026-05-12T02:31:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amafjarkasi/zephyr-developer-portal","commit_stats":null,"previous_names":["amafjarkasi/zudoku-components","amafjarkasi/zephyr-developer-portal"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/amafjarkasi/zephyr-developer-portal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amafjarkasi%2Fzephyr-developer-portal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amafjarkasi%2Fzephyr-developer-portal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amafjarkasi%2Fzephyr-developer-portal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amafjarkasi%2Fzephyr-developer-portal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amafjarkasi","download_url":"https://codeload.github.com/amafjarkasi/zephyr-developer-portal/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amafjarkasi%2Fzephyr-developer-portal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36003882,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-28T02:00:06.341Z","response_time":109,"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":["api-docs","developer-portal","documentation","mdx","openapi","react","typescript","ui-components","zudoku"],"created_at":"2026-07-28T18:30:36.659Z","updated_at":"2026-07-28T18:30:37.513Z","avatar_url":"https://github.com/amafjarkasi.png","language":"MDX","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"logo.svg\" alt=\"Zephyr\" width=\"500\" /\u003e\n\n**Production-ready API documentation that developers actually enjoy using.**\n\nA complete developer portal built with [Zudoku](https://zudoku.dev) — covering E-Commerce, Analytics, and Authentication services with interactive API references, structured guides, and 28 reusable UI component patterns.\n\n[![Built with Zudoku](https://img.shields.io/badge/Zudoku-v0.77.0-7c3aed?style=flat-square\u0026labelColor=18181b)](https://zudoku.dev)\n[![TypeScript](https://img.shields.io/badge/TypeScript-6-3178c6?style=flat-square\u0026labelColor=18181b)](https://www.typescriptlang.org/)\n[![React 19](https://img.shields.io/badge/React-19-61dafb?style=flat-square\u0026labelColor=18181b)](https://react.dev)\n[![License: MIT](https://img.shields.io/badge/License-MIT-71717a?style=flat-square\u0026labelColor=18181b)](LICENSE)\n\n\u003c/div\u003e\n\n---\n\n## Why This Exists\n\nMost API documentation is an afterthought — auto-generated, visually sterile, and hard to navigate. The Zephyr Developer Portal takes a different approach: documentation as a **designed experience**, not a byproduct of the build pipeline.\n\nWhat makes this different from a standard Swagger UI dump:\n\n- **Interactive API explorer** with live request/response examples for every endpoint\n- **Domain-organized navigation** that mirrors how developers actually discover APIs — by use case, not by HTTP method\n- **Light/dark theming** that respects developer preference and looks intentional in both modes\n- **MDX-powered content** that goes beyond specs: tutorials, migration guides, architecture overviews, and best practices all live alongside the reference material\n- **28 copy-paste component patterns** for building consistent documentation UI without reinventing the wheel\n\n---\n\n## Live Services\n\nThe portal documents three production API domains, each with a complete OpenAPI 3.0 specification:\n\n| Service | Scope | Key Endpoints |\n|---------|-------|---------------|\n| **E-Commerce** | Products, orders, inventory, shipping | CRUD operations, cart management, shipment tracking |\n| **Analytics** | Events, funnels, segments, dashboards | Event ingestion, metric queries, cohort analysis |\n| **Authentication** | OAuth 2.0, API keys, SSO providers | Token lifecycle, key rotation, provider management |\n\nEach spec lives in `apis/` as a standalone YAML file and is mapped to a route in the config — no build-time bundling or code generation required.\n\n---\n\n## Quickstart\n\n```bash\n# Clone and install\ngit clone https://github.com/amafjarkasi/zephyr-developer-portal.git\ncd zephyr-developer-portal\nnpm install\n\n# Start the dev server (http://localhost:3000)\nnpm run dev\n```\n\nThat's it. The site loads with hot-reload for MDX content. Config changes require a server restart.\n\n### All Commands\n\n| Command | What it does |\n|---------|--------------|\n| `npm run dev` | Start dev server with MDX hot-reload |\n| `npm run build` | Build static site to `dist/` |\n| `npm run preview` | Preview the production build locally |\n| `npm run lint` | Run ESLint on TypeScript files |\n\n---\n\n## Screenshots\n\nRun `npm run dev` and open http://localhost:3000 to see the full site. Below are screenshots of several component patterns from the gallery:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003eFeature Cards\u003c/b\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003eComponent Gallery\u003c/b\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"public/screenshots/feature-cards.png\" alt=\"Feature cards component\" width=\"400\" /\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"public/screenshots/components-overview.png\" alt=\"Components overview\" width=\"400\" /\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003eChangelog Timeline\u003c/b\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003eStatus Dashboard\u003c/b\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"public/screenshots/changelog.png\" alt=\"Changelog component\" width=\"400\" /\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"public/screenshots/status-page.png\" alt=\"Status page component\" width=\"400\" /\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003eAuth Flows\u003c/b\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003eIntegration Showcase\u003c/b\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"public/screenshots/auth-flows.png\" alt=\"Auth flows component\" width=\"400\" /\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"public/screenshots/integration-showcase.png\" alt=\"Integration showcase component\" width=\"400\" /\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Architecture\n\nThe entire site is driven by a single config file and a content directory. No backend, no database, no server-side rendering.\n\n### How It Works\n\n```\n┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐\n│   pages/*.mdx    │     │   apis/*.yaml    │     │ zudoku.config.tsx│\n│                  │     │                  │     │                  │\n│  Documentation   │     │  OpenAPI 3.0     │     │  Theme           │\n│  content pages   │     │  specifications  │     │  Navigation      │\n│  (64 pages)      │     │  (3 services)    │     │  API routes      │\n│                  │     │                  │     │  Metadata        │\n└────────┬─────────┘     └────────┬─────────┘     └────────┬─────────┘\n         │                        │                         │\n         └────────────────────────┼─────────────────────────┘\n                                  v\n                        ┌──────────────────┐\n                        │   Zudoku Build   │\n                        │                  │\n                        │  Static HTML     │\n                        │  + CSS + JS      │\n                        └────────┬─────────┘\n                                 v\n                        ┌──────────────────┐\n                        │     dist/        │\n                        │                  │\n                        │  Deploy anywhere │\n                        └──────────────────┘\n```\n\n### Directory Layout\n\n```\nzephyr-developer-portal/\n├── zudoku.config.tsx          # Single source of truth for the entire site\n├── pages/                     # All content (MDX)\n│   ├── introduction.mdx       #   Landing page — quickstart, pricing, overview\n│   ├── auth/                  #   Authentication: OAuth2, getting started\n│   ├── ecommerce/             #   E-Commerce: products, orders, inventory, shipping\n│   ├── analytics/             #   Analytics: events, funnels, segments\n│   ├── sdks/                  #   SDK guides: React, Python, CLI\n│   ├── integrations/          #   Webhooks, payment, third-party connections\n│   ├── advanced/              #   Architecture, error handling, rate limiting, webhooks\n│   ├── best-practices/        #   Security, performance, reliability\n│   ├── tutorials/             #   Step-by-step: first integration, batch processing, webhooks\n│   ├── guides/                #   Environments, error handling, rate limits\n│   ├── examples/              #   Full-flow: e-commerce, analytics\n│   ├── migration/             #   From v1, from Stripe, from Shopify\n│   └── components/            #   28 reusable UI component patterns\n├── apis/                      # OpenAPI 3.0 specifications\n│   ├── ecommerce.yaml         #   Products, orders, cart, inventory\n│   ├── analytics.yaml         #   Events, metrics, funnels, segments\n│   ├── auth.yaml              #   OAuth2, API keys, SSO\n│   └── openapi.yaml           #   Petstore example (placeholder)\n├── public/                    # Static assets\n│   ├── components.css          #   Component-specific CSS overrides\n│   ├── logo-*.svg              #   Branding: light/dark text variants\n│   ├── banner*.svg             #   Hero banners\n│   ├── favicon.svg             #   Site favicon\n│   └── screenshots/            #   Component gallery screenshots\n├── package.json\n├── tsconfig.json\n└── .eslintrc.json\n```\n\n### Configuration\n\nEverything is controlled from `zudoku.config.tsx`. The key sections:\n\n| Section | Purpose |\n|---------|---------|\n| `theme` | Light/dark color palettes, fonts, custom CSS (950+ lines) |\n| `site.logo` | Logo source files for light/dark mode |\n| `navigation` | Sidebar structure — categories, icons, page links, API links |\n| `apis` | Maps OpenAPI YAML files to URL routes |\n| `redirects` | URL redirects (e.g., `/` to `/introduction`) |\n| `metadata` | Site title and description |\n| `syntaxHighlighting` | Languages and Shiki themes (light: `min-light`, dark: `vitesse-dark`) |\n\n---\n\n## Content Authoring\n\n### MDX Pages\n\nEvery page requires frontmatter with a `title`. The `description` field is optional.\n\n```yaml\n---\ntitle: Managing Products\ndescription: Create, update, and delete products in your catalog\n---\n```\n\nThe frontmatter `title` is rendered by Zudoku in the page header. The custom CSS hides `article h1` elements, so use `##` (H2) and below for visible headings in the body.\n\n### Built-in Components\n\nZudoku provides several components usable directly in MDX:\n\n**Callout boxes** — for warnings, tips, and important information:\n\n```mdx\n\u003cCallout type=\"info\"\u003e\n  **Info:** This content appears in a styled callout box.\n\u003c/Callout\u003e\n```\n\nTypes: `info` | `tip` | `caution` | `warning` | `danger`\n\n**Mermaid diagrams** — for architecture and flow diagrams:\n\n```mdx\n\u003cMermaid chart={`\n  flowchart LR\n    A[Client] --\u003e B[API Gateway]\n    B --\u003e C[Auth Service]\n`} /\u003e\n```\n\n### Static Assets\n\nReference files from `public/` using absolute paths:\n\n```mdx\n![Architecture Diagram](/screenshots/architecture.png)\n```\n\n---\n\n## Component Patterns\n\nThe `pages/components/` directory contains **28 documented UI patterns** built with pure CSS and MDX. Each one is a self-contained page you can copy into your own Zudoku project.\n\n### Layout \u0026 Display\n\n| Component | Description |\n|-----------|-------------|\n| `feature-cards` | Clickable card grid with icons, descriptions, and navigation links |\n| `card-grid` | Responsive card layout for organizing related content |\n| `feature-checklist` | Feature matrix with supported/upcoming/planned status badges |\n| `integration-showcase` | Logo grid for displaying supported third-party integrations |\n| `sdk-comparison` | Side-by-side SDK matrix with installation commands per language |\n\n### Navigation\n\n| Component | Description |\n|-----------|-------------|\n| `table-of-contents` | In-page anchor navigation with active section highlighting |\n| `breadcrumb` | Hierarchical path display (Home \u003e Category \u003e Page) |\n| `prev-next-nav` | Previous/next page navigation with page titles |\n| `version-selector` | API version dropdown with `NEW` / `BETA` / `DEPRECATED` tags |\n| `sidebar-navigation` | Collapsible sidebar sections with nested items |\n| `search-component` | Search input with keyboard shortcut hints (`Ctrl+K`) |\n\n### Content\n\n| Component | Description |\n|-----------|-------------|\n| `callout-box` | Styled callouts: info, tip, warning, danger variants |\n| `alert-banner` | Dismissible banners for site-wide announcements |\n| `announcement-bar` | Gradient-background bar for promotions or updates |\n| `changelog` | Version timeline with release dates and change categories |\n| `timeline` | Chronological event sequence with status indicators |\n| `video-tutorials` | Video card grid with play buttons, thumbnails, and duration |\n| `image-lightbox` | Expandable image gallery with overlay preview |\n\n### Data \u0026 Status\n\n| Component | Description |\n|-----------|-------------|\n| `api-parameter-table` | Parameter reference: name, type, required, description |\n| `rate-limit-indicator` | Visual progress bar showing API quota usage and reset countdown |\n| `progress-indicators` | Progress bars, spinners, and skeleton loading states |\n| `status-page` | API health dashboard with uptime percentages and incident history |\n| `auth-flows` | Step-by-step OAuth2 / JWT authentication flow diagrams |\n| `badges-tags` | Inline badges for HTTP methods, status labels, and feature tags |\n| `metrics-grid` | Dashboard-style metric cards with large numbers and trends |\n\n### Feedback \u0026 Support\n\n| Component | Description |\n|-----------|-------------|\n| `page-feedback` | \"Was this page helpful?\" widget with thumbs up/down and optional comment |\n| `community-links` | Social links banner (Discord, GitHub, Twitter) |\n| `support-section` | Tiered support cards (Community / Pro / Enterprise) |\n\n---\n\n## Design System\n\n### Color Palette\n\nThe theme uses a violet-to-blue gradient accent that adapts between light and dark modes:\n\n| Token | Light Mode | Dark Mode |\n|-------|-----------|-----------|\n| Primary | `#7c3aed` (violet) | `#a78bfa` (lighter violet) |\n| Background | `#fafbfc` | `#09090b` |\n| Foreground | `#18181b` | `#fafafa` |\n| Border | `#e4e4e7` | `#27272a` |\n| Muted | `#f4f4f5` | `#27272a` |\n| Destructive | `#ef4444` | `#ef4444` |\n\nAll tokens are exposed as CSS custom properties (`--primary`, `--background`, etc.) and can be referenced in custom styles.\n\n### Typography\n\n| Role | Font | Usage |\n|------|------|-------|\n| Sans-serif | Inter | All UI text, headings, body copy |\n| Monospace | Fira Code | Code blocks, inline code, API paths |\n\n### Syntax Highlighting\n\nCode blocks use Shiki with boosted saturation (`filter: saturate(1.4)`) and a left border accent in the primary color. Themes: `min-light` for light mode, `vitesse-dark` for dark mode.\n\nThe `\"http\"` language is explicitly registered for HTTP request/response examples.\n\n### HTTP Method Badges\n\nStyled badges for API endpoint methods with distinct colors per verb:\n\n| Method | Light | Dark |\n|--------|-------|------|\n| `GET` | Green background / dark green text | Dark green background / light green text |\n| `POST` | Blue background / dark blue text | Dark blue background / light blue text |\n| `PUT` | Yellow background / dark amber text | Dark amber background / light yellow text |\n| `PATCH` | Purple background / dark purple text | Dark purple background / light purple text |\n| `DELETE` | Red background / dark red text | Dark red background / light red text |\n\n---\n\n## Adding Content\n\n### New documentation page\n\n1. Create `pages/\u003ccategory\u003e/\u003cname\u003e.mdx` with frontmatter `title`\n2. Add the path (e.g., `\"/category/name\"`) to the `navigation` array in `zudoku.config.tsx`\n3. Restart the dev server if you edited the config\n\n### New API specification\n\n1. Add an OpenAPI 3.0 YAML file to `apis/`\n2. Map it in the config: `{ type: \"file\", input: \"./apis/\u003cname\u003e.yaml\", path: \"/api/\u003cname\u003e\" }`\n3. Add a navigation link: `{ type: \"link\", label: \"\u003cName\u003e API\", to: \"/api/\u003cname\u003e\" }`\n\n### New component pattern\n\n1. Create `pages/components/\u003cname\u003e.mdx` with frontmatter `title`\n2. Add styles to `public/components.css` or `theme.customCss` in the config\n3. Add the path to the Components section of the navigation\n\n---\n\n## Deployment\n\nThe build produces a fully static site in `dist/`. No server-side rendering, no API routes, no environment variables.\n\n```bash\nnpm run build    # Output to dist/\nnpm run preview  # Verify locally before deploying\n```\n\nCompatible with any static hosting provider:\n\n| Provider | Method |\n|----------|--------|\n| Vercel | `vercel --prod` or connect repo |\n| Netlify | Drag `dist/` folder or connect repo |\n| Cloudflare Pages | Connect GitHub repo |\n| GitHub Pages | Push `dist/` to `gh-pages` branch |\n| AWS S3 + CloudFront | Upload `dist/` to bucket, configure CloudFront |\n| Any web server | Serve `dist/` as static files |\n\n---\n\n## Tech Stack\n\n| Technology | Version | Role |\n|-----------|---------|------|\n| [Zudoku](https://zudoku.dev) | 0.77.0 | Static site generator for API documentation |\n| [React](https://react.dev) | 19 | UI runtime (used internally by Zudoku) |\n| [TypeScript](https://typescriptlang.org) | 6 | Config file type safety |\n| [Mermaid](https://mermaid.js.org) | 11 | Diagram rendering in MDX content |\n| [Shiki](https://shiki.style) | bundled | Syntax highlighting with custom themes |\n| [Vite](https://vite.dev) | bundled | Build tooling (via Zudoku) |\n\n---\n\n## Resources\n\n- [Zudoku Documentation](https://zudoku.dev/docs) — Framework guides, configuration reference, component API\n- [OpenAPI 3.0 Specification](https://swagger.io/specification/) — Standard for REST API descriptions\n- [MDX Documentation](https://mdxjs.com/) — Markdown with JSX component support\n- [Mermaid Documentation](https://mermaid.js.org/) — Diagram and flowchart syntax reference\n- [Lucide Icons](https://lucide.dev/) — Icon names used in navigation configuration\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famafjarkasi%2Fzephyr-developer-portal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famafjarkasi%2Fzephyr-developer-portal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famafjarkasi%2Fzephyr-developer-portal/lists"}