docs: add Nextra documentation site

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**', '.github/workflows/docs.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+          cache-dependency-path: 'docs/pnpm-lock.yaml'
+
+      - name: Install dependencies
+        working-directory: docs
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        working-directory: docs
+        env:
+          BASE_PATH: /eventkit
+          NODE_ENV: production
+        run: pnpm build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: './docs/out'
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -8,6 +8,8 @@ Event ingestion and processing kit for Python.
 
 **Philosophy**: Provide a solid starting point with battle-tested patterns, then get out of your way. Customize for your specific needs.
 
+**📚 [View Full Documentation](https://prosdevlab.github.io/eventkit/)**
+
 ### Key Features
 
 - **Flexible ingestion** - Accept any JSON payload with Segment-compatible API

docs/.gitignore

@@ -0,0 +1,36 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Testing
+coverage/
+
+# Next.js
+.next/
+out/
+dist/
+
+# Production
+build/
+
+# Misc
+.DS_Store
+*.pem
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Local env files
+.env*.local
+.env
+
+# Vercel
+.vercel
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts

docs/README.md

@@ -0,0 +1,54 @@
+# eventkit Documentation Site
+
+This directory contains the Nextra-based documentation site for eventkit.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start dev server
+pnpm dev
+
+# Build for production
+pnpm build
+```
+
+The dev server will start at http://localhost:3000
+
+## Technology Stack
+
+- **Nextra v4.0.0** - Documentation framework
+- **Next.js 15.1.6** - React framework
+- **React 19** - UI library
+- **pnpm** - Package manager
+
+## Project Structure
+
+```
+docs/
+├── app/                    # Next.js app directory
+│   ├── layout.tsx         # Root layout with navigation
+│   └── [[...mdxPath]]/    # Dynamic MDX page routing
+├── content/               # MDX documentation files
+│   ├── _meta.json        # Navigation structure
+│   └── *.mdx             # Documentation pages
+├── public/               # Static assets
+├── next.config.mjs       # Next.js configuration
+├── tsconfig.json         # TypeScript configuration
+└── package.json          # Dependencies and scripts
+```
+
+## Deployment
+
+The site is automatically deployed to GitHub Pages at https://prosdevlab.github.io/eventkit/ when changes are pushed to the `main` branch.
+
+## Adding Content
+
+1. Create an MDX file in `content/`
+2. Add navigation entry to `content/_meta.json`
+3. Write content using MDX syntax
+4. Test locally with `pnpm dev`
+
+See [Nextra documentation](https://nextra.site/) for more details on MDX features and components.

docs/app/[[...mdxPath]]/page.tsx

@@ -0,0 +1,23 @@
+import { generateStaticParamsFor, importPage } from 'nextra/pages';
+import { useMDXComponents } from 'nextra-theme-docs';
+
+export const generateStaticParams = generateStaticParamsFor('mdxPath');
+
+export async function generateMetadata(props: { params: Promise<{ mdxPath?: string[] }> }) {
+  const params = await props.params;
+  const { metadata } = await importPage(params.mdxPath);
+  return metadata;
+}
+
+export default async function Page(props: { params: Promise<{ mdxPath?: string[] }> }) {
+  const params = await props.params;
+  const result = await importPage(params.mdxPath);
+  const { default: MDXContent, ...rest } = result;
+  const { wrapper: Wrapper } = useMDXComponents();
+
+  return (
+    <Wrapper {...rest}>
+      <MDXContent />
+    </Wrapper>
+  );
+}

docs/app/layout.tsx

@@ -0,0 +1,55 @@
+import { Banner, Head } from 'nextra/components';
+import { getPageMap } from 'nextra/page-map';
+import { Footer, Layout, Navbar } from 'nextra-theme-docs';
+import 'nextra-theme-docs/style.css';
+
+export const metadata = {
+  title: 'eventkit - Event Ingestion and Processing Kit for Python',
+  description:
+    'A production-ready kit for building event collection pipelines with flexible ingestion, stream-based routing, and pluggable storage',
+};
+
+const banner = (
+  <Banner storageKey="eventkit-banner" dismissible>
+    eventkit is in active development. APIs may change.
+  </Banner>
+);
+
+const navbar = (
+  <Navbar
+    logo={<strong>eventkit</strong>}
+    projectLink="https://github.com/prosdevlab/eventkit"
+    chatLink="https://github.com/prosdevlab/eventkit/discussions"
+  />
+);
+
+const footer = (
+  <Footer>
+    MIT {new Date().getFullYear()} ©{' '}
+    <a href="https://github.com/prosdevlab" target="_blank" rel="noreferrer">
+      ProsDevLab
+    </a>
+    .
+  </Footer>
+);
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" dir="ltr" suppressHydrationWarning>
+      <Head>
+        <link rel="icon" href="/favicon.ico" />
+      </Head>
+      <body>
+        <Layout
+          banner={banner}
+          navbar={navbar}
+          pageMap={await getPageMap()}
+          docsRepositoryBase="https://github.com/prosdevlab/eventkit/tree/main/docs/content"
+          footer={footer}
+        >
+          {children}
+        </Layout>
+      </body>
+    </html>
+  );
+}