[prosdev]

Description

Sets up a production-ready documentation site using Nextra 4.0 with automatic deployment to GitHub Pages. Reframes documentation for SDK builders with a lean, professional structure.

Type of Change

• Documentation update

Related Issue

No related issues

Changes Made

Documentation Site:

• Set up Nextra 4.0 with Next.js 15 App Router
• Configure GitHub Pages deployment workflow (.github/workflows/docs.yml)
• Create 4-page documentation structure:
  • index.mdx - Introduction with overview and quick start
  • getting-started.mdx - Building your first SDK with plugin examples
  • core-concepts.mdx - Architecture fundamentals (plugins, capabilities, events, config)
  • plugin-guide.mdx - Comprehensive plugin development guide (1400+ lines)

Documentation Reorganization:

• Move docs/plugin-development-guide.md → packages/plugins/GUIDE.md
• Update cross-references in README.md, packages/plugins/README.md, examples/minimal-sdk/README.md
• Update specs/phase-2-essential-plugins/tasks.md references

Content Strategy:

• Reframe for SDK builders (building SDKs WITH SDK Kit, not using SDK Kit as end-user library)
• Emphasize learning and experimentation angle
• Professional tone, removed emojis and marketing fluff
• Self-contained docs (no reliance on private GitHub repo access)

Testing

Manual Testing:

• Local dev server working (cd docs && pnpm dev)
• Production build succeeds (cd docs && pnpm build)
• All internal links verified
• All 4 pages render correctly
• Nextra components (Callout, Steps, Tabs) work
• Navigation structure correct

Checklist

• My code follows the project's code style (Biome)
• I have performed a self-review of my code
• I have updated the documentation accordingly
• My changes generate no new warnings
• New and existing unit tests pass locally with my changes

Additional Notes

Deployment:

• Docs will automatically deploy to https://lytics.github.io/sdk-kit/ when merged to main
• Workflow only triggers on changes to docs/** or the workflow file itself
• Completely isolated from SDK package builds (no performance impact)

Future Improvements:

• Add search functionality configuration
• Consider adding API reference section when SDK is more stable
• Add more code examples as patterns emerge from real-world usage