From 151e734aaf0ace1d4303c9292cdbb467acd46198 Mon Sep 17 00:00:00 2001 From: Kristina Quinones Date: Fri, 2 Jan 2026 10:54:05 -0500 Subject: [PATCH] doc updates. --- AGENTS.md | 57 +- CHANGELOG.md | 2 +- DOCUMENTATION.md | 146 +-- README.md | 137 +-- claude.md | 50 +- dev-docs/Deployment.md | 19 +- dev-docs/Quick-Reference.md | 468 +++------ dev-docs/Setup.md | 40 +- dev-docs/specs/EMBERDOCS-API-SPEC.md | 982 ------------------ dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md | 917 ---------------- docs/examples/api-reference/utilities.md | 32 +- docs/examples/getting-started/installation.md | 2 +- docs/examples/getting-started/introduction.md | 4 +- docs/examples/getting-started/quick-start.md | 3 +- docs/examples/guides/advanced-features.md | 53 +- docs/examples/index.md | 2 +- .../ACCESSIBILITY-AUDIT.md | 0 .../EMBERDOCS-LICENSING.md | 0 .../PROJECT-OVERVIEW.md | 28 +- framework-docs/README.md | 49 + {dev-docs => framework-docs}/USER-STORIES.md | 6 +- .../guides/ARCHITECTURE-DECISIONS.md | 20 +- .../guides/DEV-SETUP-VERIFICATION.md | 4 +- .../guides/DEVELOPMENT-STANDARDS.md | 8 +- .../guides/FEATURE-DEPENDENCIES.md | 8 +- .../planning/cli_tool_implementation.md | 0 .../deferred_frontmatter_ui_editor.md | 0 .../planning/mvp_phase01of02.md | 14 +- .../planning/mvp_phase02of02.md | 14 +- .../progress/2025_12_23_d1.1_completion.md | 2 +- .../progress/2025_12_23_d1.2_completion.md | 2 +- .../progress/2025_12_23_d1.3_completion.md | 2 +- .../progress/2025_12_23_d1456_completion.md | 0 .../progress/2025_12_23_phase02_quick_wins.md | 0 .../progress/2025_12_23_progress.md | 14 +- .../progress/2025_12_24.md | 0 .../progress/2025_12_24_ux_improvements.md | 4 +- .../progress/2025_12_27.md | 2 +- .../specs/EMBERDOCS-ROADMAP.md | 0 .../specs/EMBERDOCS-TECHNICAL-SPEC.md | 4 +- src/app/page.tsx | 6 - src/components/landing/Features.tsx | 10 +- src/lib/content.ts | 2 +- 43 files changed, 471 insertions(+), 2642 deletions(-) delete mode 100644 dev-docs/specs/EMBERDOCS-API-SPEC.md delete mode 100644 dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md rename {dev-docs => framework-docs}/ACCESSIBILITY-AUDIT.md (100%) rename {dev-docs => framework-docs}/EMBERDOCS-LICENSING.md (100%) rename {dev-docs => framework-docs}/PROJECT-OVERVIEW.md (89%) create mode 100644 framework-docs/README.md rename {dev-docs => framework-docs}/USER-STORIES.md (89%) rename {dev-docs => framework-docs}/guides/ARCHITECTURE-DECISIONS.md (93%) rename {dev-docs => framework-docs}/guides/DEV-SETUP-VERIFICATION.md (98%) rename {dev-docs => framework-docs}/guides/DEVELOPMENT-STANDARDS.md (87%) rename {dev-docs => framework-docs}/guides/FEATURE-DEPENDENCIES.md (96%) rename {dev-docs => framework-docs}/planning/cli_tool_implementation.md (100%) rename {dev-docs => framework-docs}/planning/deferred_frontmatter_ui_editor.md (100%) rename {dev-docs => framework-docs}/planning/mvp_phase01of02.md (95%) rename {dev-docs => framework-docs}/planning/mvp_phase02of02.md (94%) rename {dev-docs => framework-docs}/progress/2025_12_23_d1.1_completion.md (99%) rename {dev-docs => framework-docs}/progress/2025_12_23_d1.2_completion.md (99%) rename {dev-docs => framework-docs}/progress/2025_12_23_d1.3_completion.md (99%) rename {dev-docs => framework-docs}/progress/2025_12_23_d1456_completion.md (100%) rename {dev-docs => framework-docs}/progress/2025_12_23_phase02_quick_wins.md (100%) rename {dev-docs => framework-docs}/progress/2025_12_23_progress.md (88%) rename {dev-docs => framework-docs}/progress/2025_12_24.md (100%) rename {dev-docs => framework-docs}/progress/2025_12_24_ux_improvements.md (99%) rename {dev-docs => framework-docs}/progress/2025_12_27.md (91%) rename {dev-docs => framework-docs}/specs/EMBERDOCS-ROADMAP.md (100%) rename {dev-docs => framework-docs}/specs/EMBERDOCS-TECHNICAL-SPEC.md (99%) diff --git a/AGENTS.md b/AGENTS.md index 014f2bd..58b301c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,13 +2,13 @@ **IMPORTANT:** This file, `claude.md`, and `.cursorrules` must stay in sync. See "Sync Instructions" at bottom. -**For universal development standards applicable to any project, see:** `dev-docs/guides/DEVELOPMENT-STANDARDS.md` +**For universal development standards applicable to any project, see:** `framework-docs/guides/DEVELOPMENT-STANDARDS.md` --- ## Universal Standards (Apply to All Projects) -See `dev-docs/guides/DEVELOPMENT-STANDARDS.md` for comprehensive details on: +See `framework-docs/guides/DEVELOPMENT-STANDARDS.md` for comprehensive details on: - **Code Style:** TypeScript strict, Prettier, ESLint, naming conventions - **Testing:** Unit/integration/E2E pyramid, Jest, coverage targets ≥70% - **Git & Version Control:** Conventional Commits, branch strategy, semantic versioning @@ -45,9 +45,10 @@ npm run dev - [ ] Repo cloned and dependencies installed - [ ] Dev server running at http://localhost:3000 - [ ] All tests pass: `npm run check` -- [ ] Read `dev-docs/Quick-Reference.md` (5 min) -- [ ] Reviewed Phase 01 deliverables in `dev-docs/planning/mvp_phase01of02.md` -- [ ] Checked locked decisions in `dev-docs/guides/ARCHITECTURE-DECISIONS.md` +- [ ] Read `dev-docs/Quick-Reference.md` (5 min) - User quick reference +- [ ] Read `framework-docs/README.md` - Framework development docs overview +- [ ] Reviewed Phase 01 deliverables in `framework-docs/planning/mvp_phase01of02.md` +- [ ] Checked locked decisions in `framework-docs/guides/ARCHITECTURE-DECISIONS.md` - [ ] Configured Git user: `git config user.name "Your Name"` --- @@ -206,7 +207,7 @@ Describe what changed and why in 1–3 sentences. - [x] Manual testing in browser ## Documentation -- [x] Progress log created: `dev-docs/progress/YYYY_MM_DD.md` +- [x] Progress log created: `framework-docs/progress/YYYY_MM_DD.md` - [x] CHANGELOG.md updated under `[Unreleased]` - [x] User docs updated (if UI changed) - [x] Developer docs updated (if architecture changed) @@ -270,7 +271,7 @@ git branch -d feature/search-indexing ### Progress Log (Required) -**File:** `dev-docs/progress/YYYY_MM_DD.md` (e.g., `dev-docs/progress/2025_12_24.md`) +**File:** `framework-docs/progress/YYYY_MM_DD.md` (e.g., `framework-docs/progress/2025_12_24.md`) **Template:** ```markdown @@ -300,7 +301,7 @@ git branch -d feature/search-indexing **Format:** ```markdown ### Added -- Content pipeline module with Markdown/MDX parsing (#42) +- Content pipeline module with Markdown parsing (#42) - YAML frontmatter extraction and validation - Automatic TOC generation from headings @@ -313,7 +314,7 @@ git branch -d feature/search-indexing ### Architecture Decision (If applicable) -**File:** `dev-docs/guides/ARCHITECTURE-DECISIONS.md` +**File:** `framework-docs/guides/ARCHITECTURE-DECISIONS.md` If you made a major architectural decision, create an ADL entry: @@ -448,16 +449,16 @@ Use GitHub Discussions for: **Naming Conventions:** - **Developer docs** (`dev-docs/`): ALL CAPS with hyphens for technical docs, Title Case for user guides - - Technical examples: `ARCHITECTURE-DECISIONS.md` (in `dev-docs/guides/`), `EMBERDOCS-TECHNICAL-SPEC.md` (in `dev-docs/specs/`) + - Technical examples: `ARCHITECTURE-DECISIONS.md` (in `framework-docs/guides/`), `EMBERDOCS-TECHNICAL-SPEC.md` (in `framework-docs/specs/`) - User guide examples: `Setup.md`, `Deployment.md`, `Quick-Reference.md` (in `dev-docs/`) - **Example docs** (`docs/examples/`): kebab-case - Examples: `getting-started.md`, `api-reference.md` **Directory Structure:** -- `dev-docs/specs/` - Technical specifications (EMBERDOCS-TECHNICAL-SPEC.md, EMBERDOCS-API-SPEC.md, etc.) -- `dev-docs/guides/` - Development guides (ARCHITECTURE-DECISIONS.md, DEVELOPMENT-STANDARDS.md, etc.) -- `dev-docs/planning/` - Phase plans and planning documents -- `dev-docs/progress/` - Daily progress logs (format: `YYYY_MM_DD.md` or `YYYY_MM_DD_description.md`) +- `framework-docs/specs/` - Technical specifications (EMBERDOCS-TECHNICAL-SPEC.md, etc.) +- `framework-docs/guides/` - Development guides (ARCHITECTURE-DECISIONS.md, DEVELOPMENT-STANDARDS.md, etc.) +- `framework-docs/planning/` - Phase plans and planning documents +- `framework-docs/progress/` - Daily progress logs (format: `YYYY_MM_DD.md` or `YYYY_MM_DD_description.md`) - `dev-docs/` (root) - User guides and project overview docs (Setup.md, Deployment.md, Quick-Reference.md, PROJECT-OVERVIEW.md, etc.) - `docs/examples/` - Example documentation files (user-facing sample docs) @@ -476,9 +477,9 @@ Use GitHub Discussions for: - Fixing bugs that affect user workflows **Specific documentation to update:** -- **Technical Specs** (`dev-docs/specs/`): When architecture, API, or system design changes -- **Architecture Decisions** (`dev-docs/guides/ARCHITECTURE-DECISIONS.md`): When making major technical decisions -- **Progress Logs** (`dev-docs/progress/`): Daily (end of work day) - required for all work sessions +- **Technical Specs** (`framework-docs/specs/`): When architecture, API, or system design changes +- **Architecture Decisions** (`framework-docs/guides/ARCHITECTURE-DECISIONS.md`): When making major technical decisions +- **Progress Logs** (`framework-docs/progress/`): Daily (end of work day) - required for all work sessions - **User Docs** (`dev-docs/`): When features change or new setup steps added - **README.md**: When project overview, quick start, or key features change - **DOCUMENTATION.md**: When documentation structure changes (new files, moved files, renamed files) @@ -490,7 +491,7 @@ Use GitHub Discussions for: - [ ] Cross-references between documents are updated - [ ] Naming conventions are followed (ALL CAPS for dev docs, Title Case for user docs) - [ ] `DOCUMENTATION.md` is updated if structure changed -- [ ] Progress log created if this is a work session (`dev-docs/progress/YYYY_MM_DD.md`) +- [ ] Progress log created if this is a work session (`framework-docs/progress/YYYY_MM_DD.md`) - [ ] No broken links (verify with `grep` or link checker) - [ ] Code examples are tested and accurate - [ ] Screenshots/mockups are up to date (if applicable) @@ -498,7 +499,7 @@ Use GitHub Discussions for: ### Cross-Reference Maintenance **Always maintain accurate cross-references:** -- Use relative paths: `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (not absolute paths) +- Use relative paths: `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (not absolute paths) - When moving files, update ALL references across the codebase - Use `grep` to find all references before moving/renaming files: ```bash @@ -560,12 +561,12 @@ Use GitHub Discussions for: ## Quick Links -- **Phase Plans:** `dev-docs/planning/mvp_phase01of02.md`, `dev-docs/planning/mvp_phase02of02.md` -- **Architecture Decisions:** `dev-docs/guides/ARCHITECTURE-DECISIONS.md` -- **Developer Cheat Sheet:** `dev-docs/Quick-Reference.md` -- **Development Standards:** `dev-docs/guides/DEVELOPMENT-STANDARDS.md` -- **Setup Guide:** `dev-docs/guides/DEV-SETUP-VERIFICATION.md` -- **Feature Dependencies:** `dev-docs/guides/FEATURE-DEPENDENCIES.md` +- **Phase Plans:** `framework-docs/planning/mvp_phase01of02.md`, `framework-docs/planning/mvp_phase02of02.md` +- **Architecture Decisions:** `framework-docs/guides/ARCHITECTURE-DECISIONS.md` +- **User Quick Reference:** `dev-docs/Quick-Reference.md` +- **Development Standards:** `framework-docs/guides/DEVELOPMENT-STANDARDS.md` +- **Setup Guide:** `dev-docs/Setup.md` (user-facing) or `framework-docs/guides/DEV-SETUP-VERIFICATION.md` (contributor setup) +- **Feature Dependencies:** `framework-docs/guides/FEATURE-DEPENDENCIES.md` - **Changelog:** `CHANGELOG.md` - **PR Template:** `.github/PULL_REQUEST_TEMPLATE.md` @@ -574,9 +575,9 @@ Use GitHub Discussions for: ## Getting Help - **Code Questions:** Check `dev-docs/Quick-Reference.md` -- **Architecture Questions:** See `dev-docs/guides/ARCHITECTURE-DECISIONS.md` -- **Standards Questions:** Read `dev-docs/guides/DEVELOPMENT-STANDARDS.md` or `claude.md` -- **Setup Issues:** Follow `dev-docs/guides/DEV-SETUP-VERIFICATION.md` +- **Architecture Questions:** See `framework-docs/guides/ARCHITECTURE-DECISIONS.md` +- **Standards Questions:** Read `framework-docs/guides/DEVELOPMENT-STANDARDS.md` or `claude.md` +- **Setup Issues:** Follow `framework-docs/guides/DEV-SETUP-VERIFICATION.md` (contributors) or `dev-docs/Setup.md` (users) - **GitHub Issues:** Open an issue for bugs or feature requests - **GitHub Discussions:** Ask questions or discuss design - **Project Board:** View progress and blockers diff --git a/CHANGELOG.md b/CHANGELOG.md index c35f269..8569aa9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -82,7 +82,7 @@ This is the first alpha release containing core authoring, navigation, and searc ### Added - **Next.js 16 App Router:** TypeScript-first, strict mode, path aliases (`@/*` → `src/*`) -- **Content Pipeline:** Markdown/MDX parsing with YAML frontmatter, TOC generation, syntax highlighting (Shiki/Prism) +- **Content Pipeline:** Markdown parsing with YAML frontmatter, TOC generation, syntax highlighting (Shiki/Prism) - **Navigation Generation:** Auto-generated sidebar from file structure with breadcrumb support - **Client-Side Search:** FlexSearch index pre-built at build time, <50ms query performance, ⌘K command palette - **Theming:** Dark theme-first with light theme opt-in, CSS variables, Tailwind CSS configuration diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index d09512c..4ef1abd 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -14,68 +14,70 @@ --- -## Developer Documentation +## Framework Development Documentation -Located in `dev-docs/` - All developer-facing documentation including technical specs, guides, planning, and progress logs. +Located in `framework-docs/` - Documentation for **developing the EmberDocs framework itself** (for contributors). -### Technical Specifications (`dev-docs/specs/`) +**For users installing EmberDocs**, see [User Documentation](#user-documentation) below. + +### Technical Specifications (`framework-docs/specs/`) | Document | Description | Size | |----------|-------------|------| -| [EMBERDOCS-TECHNICAL-SPEC.md](dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md) | Complete technical overview, architecture, and system design | ~28KB | -| [EMBERDOCS-API-SPEC.md](dev-docs/specs/EMBERDOCS-API-SPEC.md) | REST and GraphQL API endpoints and contracts | ~17KB | -| [EMBERDOCS-DATABASE-SCHEMA.md](dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md) | PostgreSQL schema with Prisma ORM (for premium features) | ~26KB | -| [EMBERDOCS-ROADMAP.md](dev-docs/specs/EMBERDOCS-ROADMAP.md) | 16-week development timeline and phased plan | ~18KB | +| [EMBERDOCS-TECHNICAL-SPEC.md](framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md) | Complete technical overview, architecture, and system design | ~28KB | +| [EMBERDOCS-ROADMAP.md](framework-docs/specs/EMBERDOCS-ROADMAP.md) | 16-week development timeline and phased plan | ~18KB | -### Development Guides (`dev-docs/guides/`) +### Development Guides (`framework-docs/guides/`) | Document | Description | Purpose | |----------|-------------|---------| -| [ARCHITECTURE-DECISIONS.md](dev-docs/guides/ARCHITECTURE-DECISIONS.md) | Architecture Decision Log (ADL) - "Why" behind major technical choices | Reference locked decisions | -| [DEVELOPMENT-STANDARDS.md](dev-docs/guides/DEVELOPMENT-STANDARDS.md) | Universal development standards (code style, testing, Git workflow) | Coding guidelines | -| [DEV-SETUP-VERIFICATION.md](dev-docs/guides/DEV-SETUP-VERIFICATION.md) | Local environment setup checklist and verification steps | Onboarding | -| [FEATURE-DEPENDENCIES.md](dev-docs/guides/FEATURE-DEPENDENCIES.md) | Dependency graphs, critical path analysis, risk matrix | Planning | +| [ARCHITECTURE-DECISIONS.md](framework-docs/guides/ARCHITECTURE-DECISIONS.md) | Architecture Decision Log (ADL) - "Why" behind major technical choices | Reference locked decisions | +| [DEVELOPMENT-STANDARDS.md](framework-docs/guides/DEVELOPMENT-STANDARDS.md) | Universal development standards (code style, testing, Git workflow) | Coding guidelines | +| [DEV-SETUP-VERIFICATION.md](framework-docs/guides/DEV-SETUP-VERIFICATION.md) | Local environment setup checklist and verification steps | Onboarding | +| [FEATURE-DEPENDENCIES.md](framework-docs/guides/FEATURE-DEPENDENCIES.md) | Dependency graphs, critical path analysis, risk matrix | Planning | -### Planning Documents (`dev-docs/planning/`) +### Planning Documents (`framework-docs/planning/`) | Document | Description | |----------|-------------| -| [mvp_phase01of02.md](dev-docs/planning/mvp_phase01of02.md) | Phase 01 detailed deliverables (D1.1-D1.9) | -| [mvp_phase02of02.md](dev-docs/planning/mvp_phase02of02.md) | Phase 02 detailed deliverables (D2.1-D2.9) | -| [cli_tool_implementation.md](dev-docs/planning/cli_tool_implementation.md) | CLI tool design and implementation plan | -| [deferred_frontmatter_ui_editor.md](dev-docs/planning/deferred_frontmatter_ui_editor.md) | Deferred feature documentation | +| [mvp_phase01of02.md](framework-docs/planning/mvp_phase01of02.md) | Phase 01 detailed deliverables (D1.1-D1.9) | +| [mvp_phase02of02.md](framework-docs/planning/mvp_phase02of02.md) | Phase 02 detailed deliverables (D2.1-D2.9) | +| [cli_tool_implementation.md](framework-docs/planning/cli_tool_implementation.md) | CLI tool design and implementation plan | +| [deferred_frontmatter_ui_editor.md](framework-docs/planning/deferred_frontmatter_ui_editor.md) | Deferred feature documentation | -### Progress Logs (`dev-docs/progress/`) +### Progress Logs (`framework-docs/progress/`) Daily work logs following format: `YYYY_MM_DD.md` or `YYYY_MM_DD_description.md` **Recent logs:** -- [2025_12_27.md](dev-docs/progress/2025_12_27.md) -- [2025_12_24.md](dev-docs/progress/2025_12_24.md) -- [2025_12_24_ux_improvements.md](dev-docs/progress/2025_12_24_ux_improvements.md) -- [2025_12_23_progress.md](dev-docs/progress/2025_12_23_progress.md) +- [2025_12_27.md](framework-docs/progress/2025_12_27.md) +- [2025_12_24.md](framework-docs/progress/2025_12_24.md) +- [2025_12_24_ux_improvements.md](framework-docs/progress/2025_12_24_ux_improvements.md) +- [2025_12_23_progress.md](framework-docs/progress/2025_12_23_progress.md) -### Other Developer Docs (`dev-docs/`) +### Other Framework Docs (`framework-docs/`) | Document | Description | |----------|-------------| -| [PROJECT-OVERVIEW.md](dev-docs/PROJECT-OVERVIEW.md) | Complete package overview and quick start guide | -| [USER-STORIES.md](dev-docs/USER-STORIES.md) | User personas and stories | -| [EMBERDOCS-LICENSING.md](dev-docs/EMBERDOCS-LICENSING.md) | Licensing model and terms | -| [ACCESSIBILITY-AUDIT.md](dev-docs/ACCESSIBILITY-AUDIT.md) | Accessibility audit results and compliance | -| [Setup.md](dev-docs/Setup.md) | Installation and initial configuration | -| [Deployment.md](dev-docs/Deployment.md) | Production deployment instructions | -| [Quick-Reference.md](dev-docs/Quick-Reference.md) | Developer cheat sheet (common commands, patterns, FAQ) | +| [README.md](framework-docs/README.md) | Overview of framework development documentation | +| [PROJECT-OVERVIEW.md](framework-docs/PROJECT-OVERVIEW.md) | Complete package overview and framework architecture | +| [USER-STORIES.md](framework-docs/USER-STORIES.md) | User personas and stories for framework planning | +| [EMBERDOCS-LICENSING.md](framework-docs/EMBERDOCS-LICENSING.md) | Licensing model and terms | +| [ACCESSIBILITY-AUDIT.md](framework-docs/ACCESSIBILITY-AUDIT.md) | Accessibility audit results and compliance | --- ## User Documentation -Located in `dev-docs/` - Setup, deployment, and usage guides for developers and end users. +Located in `dev-docs/` - Setup, deployment, and usage guides for **users installing and using EmberDocs**. -**Note:** User documentation is now located in `dev-docs/` alongside developer documentation. The distinction is: -- **Developer docs** (specs/, guides/, planning/, progress/): Technical documentation for contributors -- **User docs** (Setup.md, Deployment.md, Quick-Reference.md): Guides for using and deploying EmberDocs +**Note:** This is separate from framework development documentation (see [Framework Development Documentation](#framework-development-documentation) above). + +| Document | Description | +|----------|-------------| +| [Setup.md](dev-docs/Setup.md) | Installation and initial configuration | +| [Deployment.md](dev-docs/Deployment.md) | Production deployment instructions | +| [Quick-Reference.md](dev-docs/Quick-Reference.md) | User quick reference (common commands, troubleshooting) | **Naming Convention:** Title Case (e.g., `Setup.md`, `Deployment.md`, `Quick-Reference.md`) @@ -138,20 +140,19 @@ See [UI-MOCKUPS-GUIDE.md](mockups/ui/UI-MOCKUPS-GUIDE.md) and [LANDING-MOCKUPS-G ## Naming Conventions -### Developer Documentation (`dev-docs/`) +### Framework Development Documentation (`framework-docs/`) **Format:** ALL CAPS with hyphens **Examples:** - `ARCHITECTURE-DECISIONS.md` - `DEVELOPMENT-STANDARDS.md` - `EMBERDOCS-TECHNICAL-SPEC.md` -- `EMBERDOCS-API-SPEC.md` **Organization:** -- `dev-docs/specs/` - Technical specifications -- `dev-docs/guides/` - Development guides -- `dev-docs/planning/` - Phase plans and planning docs -- `dev-docs/progress/` - Daily progress logs +- `framework-docs/specs/` - Technical specifications +- `framework-docs/guides/` - Development guides +- `framework-docs/planning/` - Phase plans and planning docs +- `framework-docs/progress/` - Daily progress logs ### User Documentation (`dev-docs/`) @@ -176,24 +177,22 @@ See [UI-MOCKUPS-GUIDE.md](mockups/ui/UI-MOCKUPS-GUIDE.md) and [LANDING-MOCKUPS-G ### By Purpose **Getting Started:** -1. [README.md](README.md) - Project overview -2. [dev-docs/Setup.md](dev-docs/Setup.md) - Installation -3. [dev-docs/Quick-Reference.md](dev-docs/Quick-Reference.md) - Common commands +1. [README.md](README.md) - Project overview and quick start +2. [dev-docs/Setup.md](dev-docs/Setup.md) - Installation and configuration +3. [dev-docs/Quick-Reference.md](dev-docs/Quick-Reference.md) - Common commands and troubleshooting -**Understanding Architecture:** -1. [dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md](dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md) - System design -2. [dev-docs/guides/ARCHITECTURE-DECISIONS.md](dev-docs/guides/ARCHITECTURE-DECISIONS.md) - Decision log -3. [dev-docs/specs/EMBERDOCS-API-SPEC.md](dev-docs/specs/EMBERDOCS-API-SPEC.md) - API design +**Deploying:** +1. [dev-docs/Deployment.md](dev-docs/Deployment.md) - Deploy to Vercel, Netlify, or self-hosted -**Contributing:** -1. [AGENTS.md](AGENTS.md) - Contributing workflow -2. [dev-docs/guides/DEVELOPMENT-STANDARDS.md](dev-docs/guides/DEVELOPMENT-STANDARDS.md) - Coding standards -3. [dev-docs/guides/DEV-SETUP-VERIFICATION.md](dev-docs/guides/DEV-SETUP-VERIFICATION.md) - Setup verification +**Customizing:** +1. [brand/EMBERDOCS-STYLE-GUIDE.md](brand/EMBERDOCS-STYLE-GUIDE.md) - Themes, colors, and branding +2. [brand/emberdocs-brand-guidelines.md](brand/emberdocs-brand-guidelines.md) - Logo usage -**Planning:** -1. [dev-docs/specs/EMBERDOCS-ROADMAP.md](dev-docs/specs/EMBERDOCS-ROADMAP.md) - Development timeline -2. [dev-docs/planning/mvp_phase01of02.md](dev-docs/planning/mvp_phase01of02.md) - Phase 01 plan -3. [dev-docs/guides/FEATURE-DEPENDENCIES.md](dev-docs/guides/FEATURE-DEPENDENCIES.md) - Dependency analysis +**Contributing (for framework contributors):** +1. [AGENTS.md](AGENTS.md) - Contributing workflow +2. [framework-docs/README.md](framework-docs/README.md) - Framework development docs overview +3. [framework-docs/guides/DEVELOPMENT-STANDARDS.md](framework-docs/guides/DEVELOPMENT-STANDARDS.md) - Coding standards +4. [framework-docs/guides/DEV-SETUP-VERIFICATION.md](framework-docs/guides/DEV-SETUP-VERIFICATION.md) - Development setup --- @@ -201,18 +200,20 @@ See [UI-MOCKUPS-GUIDE.md](mockups/ui/UI-MOCKUPS-GUIDE.md) and [LANDING-MOCKUPS-G ### When to Update -- **Technical Specs** (`dev-docs/specs/`): When architecture or API changes -- **Architecture Decisions** (`dev-docs/guides/ARCHITECTURE-DECISIONS.md`): When making major technical decisions -- **Progress Logs** (`dev-docs/progress/`): Daily (end of work day) +- **Framework Development Docs** (`framework-docs/`): When developing the framework itself + - Technical Specs (`framework-docs/specs/`): When architecture or API changes + - Architecture Decisions (`framework-docs/guides/ARCHITECTURE-DECISIONS.md`): When making major technical decisions + - Progress Logs (`framework-docs/progress/`): Daily (end of work day) - **User Docs** (`dev-docs/`): When features change or new setup steps added - **README.md**: When project overview or quick start changes ### Cross-References All documentation should cross-reference related documents. Use relative paths: -- `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` -- `dev-docs/guides/ARCHITECTURE-DECISIONS.md` -- `dev-docs/Quick-Reference.md` +- `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (framework development) +- `framework-docs/guides/ARCHITECTURE-DECISIONS.md` (framework development) +- `dev-docs/Setup.md` (user-facing) +- `dev-docs/Quick-Reference.md` (user-facing) --- @@ -220,15 +221,20 @@ All documentation should cross-reference related documents. Use relative paths: **Most Frequently Used:** - [README.md](README.md) - Start here -- [dev-docs/Quick-Reference.md](dev-docs/Quick-Reference.md) - Developer cheat sheet -- [dev-docs/guides/ARCHITECTURE-DECISIONS.md](dev-docs/guides/ARCHITECTURE-DECISIONS.md) - Locked decisions -- [AGENTS.md](AGENTS.md) - Contributing guidelines - -**For New Contributors:** -1. Read [README.md](README.md) -2. Follow [dev-docs/guides/DEV-SETUP-VERIFICATION.md](dev-docs/guides/DEV-SETUP-VERIFICATION.md) -3. Review [AGENTS.md](AGENTS.md) -4. Bookmark [dev-docs/Quick-Reference.md](dev-docs/Quick-Reference.md) +- [dev-docs/Setup.md](dev-docs/Setup.md) - Installation and configuration +- [dev-docs/Quick-Reference.md](dev-docs/Quick-Reference.md) - Common commands and troubleshooting +- [dev-docs/Deployment.md](dev-docs/Deployment.md) - Deployment guide + +**For New Users:** +1. Read [README.md](README.md) for overview +2. Follow [dev-docs/Setup.md](dev-docs/Setup.md) for installation +3. Bookmark [dev-docs/Quick-Reference.md](dev-docs/Quick-Reference.md) for common tasks +4. See [dev-docs/Deployment.md](dev-docs/Deployment.md) when ready to deploy + +**For Contributors:** +1. Read [AGENTS.md](AGENTS.md) for contributing guidelines +2. See [framework-docs/README.md](framework-docs/README.md) for framework development docs +3. Follow [framework-docs/guides/DEV-SETUP-VERIFICATION.md](framework-docs/guides/DEV-SETUP-VERIFICATION.md) for development setup --- diff --git a/README.md b/README.md index 4cee398..c19b911 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # EmberDocs -> Modern documentation framework with Git-native versioning, instant search, and developer-focused design. +> Modern documentation framework with instant search and developer-focused design. [![License](https://img.shields.io/badge/License-Source%20Available-lightgrey.svg)](LICENSE) [![Status](https://img.shields.io/badge/Status-In%20Development-yellow.svg)]() @@ -70,7 +70,6 @@ EMBERDOCS_BASE_ROUTE=/documentation # URLs at /documentation/* EmberDocs is a modern documentation framework designed for developers who want: -- **Git-Native Versioning** - Version detection from Git tags (routing planned for Phase 02) - **Instant Search** - <50ms for typical queries (FlexSearch with ⌘K shortcuts) - **Dark Theme First** - Developer-focused dark UI with light mode support - **Mobile Optimized** - Touch-optimized responsive design @@ -96,144 +95,63 @@ EmberDocs is a modern documentation framework designed for developers who want: ``` emberdocs/ -├── docs/ # 📋 Example documentation (user-facing) -│ └── examples/ # Sample docs for testing/demonstration -├── dev-docs/ # 💻 Developer documentation -│ ├── specs/ # Technical specifications -│ │ ├── EMBERDOCS-TECHNICAL-SPEC.md -│ │ ├── EMBERDOCS-DATABASE-SCHEMA.md -│ │ ├── EMBERDOCS-API-SPEC.md -│ │ └── EMBERDOCS-ROADMAP.md -│ ├── guides/ # Development guides -│ │ ├── ARCHITECTURE-DECISIONS.md -│ │ ├── DEVELOPMENT-STANDARDS.md -│ │ ├── DEV-SETUP-VERIFICATION.md -│ │ └── FEATURE-DEPENDENCIES.md -│ ├── planning/ # Phase plans (e.g., mvp_phase01of02.md) -│ ├── progress/ # Daily progress logs -│ ├── PROJECT-OVERVIEW.md # Complete package overview -│ ├── USER-STORIES.md # User stories & personas -│ ├── EMBERDOCS-LICENSING.md # Licensing model -│ ├── ACCESSIBILITY-AUDIT.md # Accessibility audit results -│ ├── Setup.md # Installation guide -│ ├── Deployment.md # Deployment guide -│ └── Quick-Reference.md # Developer cheat sheet -├── brand/ # 🎨 Brand & design system -│ ├── emberdocs-brand-guidelines.md -│ └── EMBERDOCS-STYLE-GUIDE.md -├── mockups/ # 🖼 UI/UX mockups -│ ├── landing/ # Landing page variations -│ └── ui/ # Application UI screens -├── logos/ # 🔥 Logo assets -└── src/ # 💻 Source code +├── docs/ # Your documentation files +│ └── examples/ # Default location (customize via EMBERDOCS_CONTENT_DIR) +├── public/ # Static assets (logos, images) +├── src/ # Framework source code +└── .env.local # Your configuration (create from .env.example) ``` +**Key directories:** +- `docs/` - Place your markdown files here (or customize the path) +- `public/` - Add logos, images, and other static assets +- `.env.local` - Configuration file (never commit this) + --- ## 📚 Documentation -### For Developers - -- **[Technical Specification](dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md)** - Complete technical overview -- **[Database Schema](dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md)** - Data models and storage -- **[API Specification](dev-docs/specs/EMBERDOCS-API-SPEC.md)** - REST and GraphQL endpoints -- **[Roadmap](dev-docs/specs/EMBERDOCS-ROADMAP.md)** - Phased development plan -- **[User Stories](dev-docs/USER-STORIES.md)** - User personas and stories - -### For Designers +### Getting Started -- **[Style Guide](brand/EMBERDOCS-STYLE-GUIDE.md)** - Complete design system -- **[Brand Guidelines](brand/emberdocs-brand-guidelines.md)** - Logo usage and brand identity -- **[UI Mockups](mockups/ui/UI-MOCKUPS-GUIDE.md)** - Application screen designs -- **[Landing Mockups](mockups/landing/LANDING-MOCKUPS-GUIDE.md)** - Marketing page variations - -### For Contributors - -- **[Development Roadmap](dev-docs/specs/EMBERDOCS-ROADMAP.md)** - 16-week development timeline -- **[Licensing](dev-docs/EMBERDOCS-LICENSING.md)** - Proprietary core license (source-available) +- **[Setup Guide](dev-docs/Setup.md)** - Complete installation and configuration guide +- **[Deployment Guide](dev-docs/Deployment.md)** - Deploy to Vercel, Netlify, or self-hosted +- **[Quick Reference](dev-docs/Quick-Reference.md)** - Common commands and configuration options --- ## 🎯 Key Features ### Core Features -- ✅ Markdown & MDX support -- ✅ Git-based versioning +- ✅ Markdown support with YAML frontmatter - ✅ Full-text search (<50ms for typical queries) -- ✅ Dark/light themes -- ✅ Mobile responsive +- ✅ Dark/light/monochrome themes +- ✅ Mobile responsive design - ✅ Code syntax highlighting - ✅ Table of contents auto-generation -### Advanced Features -- 🔄 Multi-language support (planned) -- 🔄 API documentation generator -- 🔄 Interactive examples -- 🔄 Version comparison -- 🔄 Privacy-first analytics - --- -## 📊 Performance Targets - -| Metric | Target | Current | -|--------|--------|---------| -| Search Response | <50ms (typical) | <50ms for typical queries | -| Initial Load (TTI) | <1s | - | -| Build Time | <1s per page | ~30s for 1000 docs | -| Lighthouse Score | 100/100/100/100 | ~90 accessibility, ~85 performance | --- -## 🗺 Development Phases - -### **MVP** (Weeks 1-6) -Core documentation engine with markdown parsing, basic search, and dark mode. - -### **Beta** (Weeks 7-12) -Multi-version support, advanced search, mobile navigation, and CLI tool. - -### **v1.0** (Weeks 13-16) -Performance optimization and hosted service. - -👉 **[View Detailed Roadmap](dev-docs/specs/EMBERDOCS-ROADMAP.md)** --- ## 🔐 License - **Core Framework:** Proprietary source-available license (free to use and self-host; redistribution is not permitted) -- **Hosted Service:** Proprietary (optional premium offering) +- **Hosted Service:** Proprietary (optional premium offering - coming soon) -See **[EMBERDOCS-LICENSING.md](dev-docs/EMBERDOCS-LICENSING.md)** for details. +See **[EMBERDOCS-LICENSING.md](framework-docs/EMBERDOCS-LICENSING.md)** for details. --- -## 🤝 Contributing - -We welcome your feedback and bug reports! The best way to contribute is by submitting Issues: +## 🤝 Support & Feedback - **Bug Reports** - Found a bug? [Open an issue](https://github.com/sturdy-barnacle/emberdocs/issues/new?template=bug_report.md) - **Feature Requests** - Have an idea? [Suggest a feature](https://github.com/sturdy-barnacle/emberdocs/issues/new?template=feature_request.md) -- **Documentation** - Found an error or have a suggestion? [Report it](https://github.com/sturdy-barnacle/emberdocs/issues/new) - **Questions** - Use [GitHub Discussions](https://github.com/sturdy-barnacle/emberdocs/discussions) for questions and community discussion - -### Development Setup - -If you'd like to contribute code, here's how to set up your development environment: - -```bash -# Install dependencies -npm install - -# Run tests -npm test - -# Start development -npm run dev -``` - -**Note:** By submitting code contributions, you grant us a license to use your contribution as part of EmberDocs under our proprietary license. See [LICENSE](LICENSE) section 4 for details. +- **Contributing** - Want to contribute code? See [Contributing Guidelines](AGENTS.md) --- @@ -247,11 +165,6 @@ npm run dev --- -## 📞 Support & Community - -- **Documentation:** Coming soon -- **Issues:** [GitHub Issues](https://github.com/sturdy-barnacle/emberdocs/issues) -- **Discussions:** [GitHub Discussions](https://github.com/sturdy-barnacle/emberdocs/discussions) --- @@ -261,7 +174,11 @@ Built with: - [Next.js](https://nextjs.org/) - React framework - [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS - [FlexSearch](https://github.com/nextapps-de/flexsearch) - Full-text search +- [react-markdown](https://github.com/remarkjs/react-markdown) - Markdown rendering +- [remark-gfm](https://github.com/remarkjs/remark-gfm) - GitHub Flavored Markdown support +- [Shiki](https://shiki.matsu.io/) - Syntax highlighting +- [Prism.js](https://prismjs.com/) - Code syntax highlighting --- -**Made with 🔥 by the EmberDocs team** +**Made with 🔥 by Kristina Quinones** diff --git a/claude.md b/claude.md index fb75dcf..2c05412 100644 --- a/claude.md +++ b/claude.md @@ -2,13 +2,13 @@ **IMPORTANT:** This file, `.cursorrules`, and `AGENTS.md` must stay in sync. See "Sync Instructions" at bottom. -**For universal development standards applicable to any project, see:** `dev-docs/guides/DEVELOPMENT-STANDARDS.md` +**For universal development standards applicable to any project, see:** `framework-docs/guides/DEVELOPMENT-STANDARDS.md` --- ## Universal Standards (Apply to All Projects) -See `dev-docs/guides/DEVELOPMENT-STANDARDS.md` for comprehensive details on: +See `framework-docs/guides/DEVELOPMENT-STANDARDS.md` for comprehensive details on: - **Philosophy & Principles:** Clarity over cleverness, DRY, YAGNI, fail fast, documentation as code - **Code Organization:** Directory structure, module organization, functional cohesion - **Coding Style:** TypeScript strict mode, naming conventions (PascalCase/camelCase/kebab-case), formatting (Prettier, ESLint) @@ -30,7 +30,7 @@ See `dev-docs/guides/DEVELOPMENT-STANDARDS.md` for comprehensive details on: ### Project Overview EmberDocs is a documentation platform built with Next.js 16, TypeScript, and Tailwind CSS. It features: -- **Fast Content Pipeline:** Markdown/MDX parsing with YAML frontmatter +- **Fast Content Pipeline:** Markdown parsing with YAML frontmatter - **Auto-Generated Navigation:** Sidebar built from file structure - **Client-Side Search:** FlexSearch pre-built at build time, <100ms queries - **Dark-First Theme:** CSS variables with light theme opt-in @@ -46,7 +46,8 @@ src/ └── styles/ # Global CSS, design tokens, Tailwind config docs/ # Example documentation (docs/examples/ only) -dev-docs/ # Developer documentation (specs/, guides/, planning/, progress/, and user guides) +dev-docs/ # User-facing documentation (Setup.md, Deployment.md, Quick-Reference.md) +framework-docs/ # Framework development documentation (specs/, guides/, planning/, progress/) brand/ # Design assets, logos, style guide ``` @@ -55,15 +56,16 @@ brand/ # Design assets, logos, style guide - `src/lib/navigation.ts` — Navigation generator - `src/lib/search.ts` — Search indexing - `src/app/docs/[...slug]/page.tsx` — Doc page renderer -- `dev-docs/guides/ARCHITECTURE-DECISIONS.md` — Locked decisions (ADL-001 through ADL-012) -- `dev-docs/Quick-Reference.md` — Developer cheat sheet +- `framework-docs/guides/ARCHITECTURE-DECISIONS.md` — Locked decisions (ADL-001 through ADL-012) +- `dev-docs/Quick-Reference.md` — User quick reference ### Development Workflow **Before starting work:** -1. Read `dev-docs/Quick-Reference.md` (5 min overview) -2. Understand Phase 01 deliverables in `dev-docs/planning/mvp_phase01of02.md` -3. Check `dev-docs/guides/ARCHITECTURE-DECISIONS.md` for locked decisions +1. Read `dev-docs/Quick-Reference.md` (5 min overview) - User quick reference +2. Read `framework-docs/README.md` - Framework development docs overview +3. Understand Phase 01 deliverables in `framework-docs/planning/mvp_phase01of02.md` +4. Check `framework-docs/guides/ARCHITECTURE-DECISIONS.md` for locked decisions **While coding:** ```bash @@ -124,7 +126,7 @@ export function parse(x: any): any { Each PR must include: -1. **Progress Log** — Create `dev-docs/progress/YYYY_MM_DD.md` +1. **Progress Log** — Create `framework-docs/progress/YYYY_MM_DD.md` ```markdown # Progress: 2025-12-24 ## Summary @@ -146,12 +148,12 @@ Each PR must include: 2. **Changelog Update** — Add to `CHANGELOG.md` under `[Unreleased]` ```markdown ### Added - - Content pipeline module with Markdown/MDX parsing (#PR) + - Content pipeline module with Markdown parsing (#PR) - YAML frontmatter extraction and validation - Automatic TOC generation from headings ``` -3. **Architecture Decision** — If major decision made, create ADL entry in `dev-docs/guides/ARCHITECTURE-DECISIONS.md` +3. **Architecture Decision** — If major decision made, create ADL entry in `framework-docs/guides/ARCHITECTURE-DECISIONS.md` ```markdown ## ADL-XXX: [Decision Title] **Date:** YYYY-MM-DD @@ -259,7 +261,7 @@ These decisions are fixed for Phase 01–02. Follow them: - **ADL-011:** Hybrid testing (TDD for D1.1; implement-then-test for D1.2–D1.4) - **ADL-012:** WCAG 2.1 Level AA accessibility (US ADA + EU compliance) -See `dev-docs/guides/ARCHITECTURE-DECISIONS.md` for full context. +See `framework-docs/guides/ARCHITECTURE-DECISIONS.md` for full context. ### Design & Branding @@ -281,10 +283,10 @@ See `dev-docs/guides/ARCHITECTURE-DECISIONS.md` for full context. - **Example docs** (`docs/examples/`): kebab-case (e.g., `getting-started.md`, `api-reference.md`) **Directory Structure:** -- `dev-docs/specs/` - Technical specifications (EMBERDOCS-TECHNICAL-SPEC.md, EMBERDOCS-API-SPEC.md, etc.) -- `dev-docs/guides/` - Development guides (ARCHITECTURE-DECISIONS.md, DEVELOPMENT-STANDARDS.md, etc.) -- `dev-docs/planning/` - Phase plans and planning documents -- `dev-docs/progress/` - Daily progress logs (YYYY_MM_DD.md format) +- `framework-docs/specs/` - Technical specifications (EMBERDOCS-TECHNICAL-SPEC.md, etc.) +- `framework-docs/guides/` - Development guides (ARCHITECTURE-DECISIONS.md, DEVELOPMENT-STANDARDS.md, etc.) +- `framework-docs/planning/` - Phase plans and planning documents +- `framework-docs/progress/` - Daily progress logs (YYYY_MM_DD.md format) - `dev-docs/` (root) - User guides and project overview docs (Setup.md, Deployment.md, Quick-Reference.md, PROJECT-OVERVIEW.md, etc.) - `docs/examples/` - Example documentation files (user-facing sample docs) @@ -296,16 +298,16 @@ See `dev-docs/guides/ARCHITECTURE-DECISIONS.md` for full context. **Always update when:** - Adding new features or changing existing functionality -- Making architectural decisions (create ADL entry in `dev-docs/guides/ARCHITECTURE-DECISIONS.md`) +- Making architectural decisions (create ADL entry in `framework-docs/guides/ARCHITECTURE-DECISIONS.md`) - Changing setup or deployment processes - Updating dependencies or tools - Completing deliverables (update progress logs) - Fixing bugs that affect user workflows **Update specific docs:** -- **Technical Specs** (`dev-docs/specs/`): When architecture, API, or system design changes -- **Architecture Decisions** (`dev-docs/guides/ARCHITECTURE-DECISIONS.md`): When making major technical decisions -- **Progress Logs** (`dev-docs/progress/`): Daily (end of work day) - use format `YYYY_MM_DD.md` +- **Technical Specs** (`framework-docs/specs/`): When architecture, API, or system design changes +- **Architecture Decisions** (`framework-docs/guides/ARCHITECTURE-DECISIONS.md`): When making major technical decisions +- **Progress Logs** (`framework-docs/progress/`): Daily (end of work day) - use format `YYYY_MM_DD.md` - **User Docs** (`dev-docs/`): When features change or new setup steps added - **README.md**: When project overview, quick start, or key features change - **DOCUMENTATION.md**: When documentation structure changes (new files, moved files, renamed files) @@ -325,7 +327,7 @@ Before committing documentation changes: ### Cross-Reference Maintenance **Always maintain accurate cross-references:** -- Use relative paths: `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (not absolute paths) +- Use relative paths: `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (not absolute paths) - When moving files, update ALL references across the codebase - Use `grep` to find all references before moving/renaming files: ```bash @@ -365,9 +367,9 @@ Before committing documentation changes: - Include sync instructions in each file **Changes requiring sync:** -- New coding style rule → add to all three + dev-docs/guides/DEVELOPMENT-STANDARDS.md +- New coding style rule → add to all three + framework-docs/guides/DEVELOPMENT-STANDARDS.md - New tool/dependency → add to all three - New documentation requirement → add to all three -- Architecture decision locked → create ADL entry + update all three + dev-docs/guides/DEVELOPMENT-STANDARDS.md +- Architecture decision locked → create ADL entry + update all three + framework-docs/guides/DEVELOPMENT-STANDARDS.md - Phase plan updated → reflect in all three - Documentation structure/organization changed → update all three + DOCUMENTATION.md diff --git a/dev-docs/Deployment.md b/dev-docs/Deployment.md index 63d679e..20cb503 100644 --- a/dev-docs/Deployment.md +++ b/dev-docs/Deployment.md @@ -2,14 +2,12 @@ Goal: deploy EmberDocs with predictable, repeatable steps. -## Build & Test Before Deploy +## Build Before Deploy ```bash -npm run lint -npm run typecheck -npm run test npm run build ``` -- Resolve failures locally before shipping. +- This creates an optimized production build +- Resolve any build errors before deploying ## Environment Configuration - Copy `.env.example` to `.env.local` for local runs and to your platform’s env settings for deploys. @@ -22,10 +20,11 @@ npm run build - Self-host: build once, then `npm run start` behind a reverse proxy (TLS, caching as needed). ## Versioning & Releases -- Tag releases with `vX.Y.Z` to align with git-native versioning and doc routing once implemented. -- Keep `dev-docs/planning/` and `dev-docs/progress/` updated; link the relevant entries in your release notes/PR. +- Tag releases with `vX.Y.Z` to align with git-native versioning (when implemented) +- Use semantic versioning: `v1.0.0`, `v1.1.0`, `v2.0.0`, etc. ## Post-Deploy Checks -- Smoke-test navigation, search, and version selector (if enabled). -- Verify env-flagged integrations behave correctly when missing or disabled. -- Record deploy outcomes and any incidents in `dev-docs/progress/` for the deployment day. +- Test navigation and search functionality +- Verify all pages load correctly +- Check that environment variables are set correctly on your hosting platform +- Test on mobile devices to ensure responsive design works diff --git a/dev-docs/Quick-Reference.md b/dev-docs/Quick-Reference.md index 23d43c8..3bd019b 100644 --- a/dev-docs/Quick-Reference.md +++ b/dev-docs/Quick-Reference.md @@ -1,6 +1,6 @@ -# EmberDocs Developer Quick Reference +# EmberDocs Quick Reference -**Bookmark this page.** This is your command reference for common development tasks. +**Bookmark this page.** Quick reference for setting up and using EmberDocs. --- @@ -12,7 +12,7 @@ git clone https://github.com/sturdy-barnacle/emberdocs.git cd emberdocs npm install -# First time only: seed environment variables +# First time only: configure environment cp .env.example .env.local # Start development server @@ -24,163 +24,35 @@ open http://localhost:3000 --- -## Common npm Scripts +## Common Commands -| Command | Purpose | Duration | -|---------|---------|----------| -| `npm run dev` | Start Next.js dev server with hot reload | Instant | -| `npm run build` | Build static/optimized app for production | ~30s (1000 docs) | -| `npm run lint` | ESLint + Prettier formatting check | ~5s | -| `npm run format` | Auto-fix formatting with Prettier | ~5s | -| `npm run typecheck` | TypeScript type checking (strict mode) | ~10s | -| `npm test` | Run Jest unit + integration tests | ~10s | -| `npm run check` | Run all: lint + typecheck + test | ~30s | - -**Before pushing:** Always run `npm run check` to catch issues early. +| Command | Purpose | When to Use | +|---------|---------|-------------| +| `npm run dev` | Start development server | Local development | +| `npm run build` | Build for production | Before deploying | +| `npm run build:search` | Rebuild search index | After changing content directory or adding many docs | +| `npm start` | Start production server | Test production build locally | --- -## Project Structure at a Glance - -``` -src/ -├── app/ # Next.js App Router -│ ├── layout.tsx # Root layout (header, nav, footer) -│ ├── page.tsx # Homepage -│ ├── docs/[...slug]/ # Dynamic doc routes -│ └── globals.css # Global styles (dark/light theme) -└── lib/ # Reusable modules - ├── content.ts # Markdown parsing, TOC generation - ├── search.ts # FlexSearch indexing - ├── navigation.ts # Sidebar nav generation - ├── versioning.ts # Git version detection (Phase 02) - -docs/ -└── examples/ # Example documentation (user-facing sample docs) - -dev-docs/ # Developer documentation -├── specs/ # Technical specifications -│ ├── EMBERDOCS-TECHNICAL-SPEC.md -│ ├── EMBERDOCS-API-SPEC.md -│ ├── EMBERDOCS-DATABASE-SCHEMA.md -│ └── EMBERDOCS-ROADMAP.md -├── guides/ # Development guides -│ ├── ARCHITECTURE-DECISIONS.md -│ ├── DEVELOPMENT-STANDARDS.md -│ ├── DEV-SETUP-VERIFICATION.md -│ └── FEATURE-DEPENDENCIES.md -├── planning/ # Phase plans (mvp_phase01of02.md, etc.) -├── progress/ # Daily logs (YYYY_MM_DD.md) -├── PROJECT-OVERVIEW.md # Complete package overview -├── USER-STORIES.md # User personas and stories -├── EMBERDOCS-LICENSING.md # Licensing model -├── ACCESSIBILITY-AUDIT.md # Accessibility audit results -├── Setup.md # Installation guide -├── Deployment.md # Deployment guide -└── Quick-Reference.md # This file - Developer cheat sheet - -tests/ # Jest unit tests + Playwright e2e -brand/ # Design assets and style guide -``` - -**Key rule:** `src/` = app code. `docs/examples/` = example user-facing docs. `dev-docs/` = all developer documentation. - ---- - -## Writing Tests - -### Unit Test Template (Jest) +## Creating Documentation -```typescript -// src/lib/content.test.ts -import { parseMarkdown } from './content'; - -describe('parseMarkdown', () => { - it('should extract frontmatter and body', () => { - const markdown = `--- -title: "Test Doc" -slug: "test-doc" ---- - -# Heading - -Body text.`; - const result = parseMarkdown(markdown); - - expect(result.frontmatter.title).toBe('Test Doc'); - expect(result.content).toContain('# Heading'); - }); +### 1. Create Markdown File - it('should validate required frontmatter fields', () => { - const invalidMarkdown = `--- -slug: "missing-title" ---- -Body`; +Place your markdown files in your documentation directory (default: `docs/examples/`): - expect(() => parseMarkdown(invalidMarkdown)).toThrow('title is required'); - }); -}); -``` - -**Run tests:** ```bash -npm test # All tests -npm test -- --watch # Watch mode (re-run on save) -npm test -- --coverage # Coverage report -npm test -- pattern.test.ts # Single file -``` - ---- - -## Styling Guide - -### Use Tailwind First -```tsx -// ✅ Good: Tailwind utilities -
- Content -
- -// ❌ Avoid: Custom CSS or inline styles -
- Content -
-``` +# Default location +docs/examples/my-guide.md -### Using CSS Variables (Theme Colors) -```typescript -// src/app/globals.css -:root { - --color-primary: #7f5af0; - --color-background: #ffffff; - --color-text: #1a1a1a; -} - -[data-theme='dark'] { - --color-background: #0a0a0a; - --color-text: #f5f5f5; -} +# Or custom location (if EMBERDOCS_CONTENT_DIR is set) +docs/content/my-guide.md ``` -```tsx -// In React component -
- Theme-aware content -
-``` - ---- - -## Creating a New Document +### 2. Add Frontmatter -### 1. Create Markdown File -```bash -# Save to dev-docs/guides/my-guide.md -mkdir -p dev-docs/guides -touch dev-docs/guides/my-guide.md -``` +Every markdown file needs frontmatter at the top: -### 2. Add Frontmatter ```markdown --- title: "My Guide" @@ -188,240 +60,164 @@ slug: "my-guide" published: true date: "2025-12-23" author: "Your Name" +order: 1 --- # My Guide -Content here... +Your content here... ``` -### 3. Test Locally +**Required fields:** +- `title` - Document title (shown in sidebar and page header) +- `slug` - URL-safe identifier (used in URLs: `/docs/my-guide`) + +**Optional fields:** +- `published` - Set to `false` to hide from navigation (default: `true`) +- `date` - Publication date +- `author` - Author name (or use `EMBERDOCS_DEFAULT_AUTHOR` env var) +- `tags` - Comma-separated tags +- `order` - Custom sidebar order (lower numbers appear first) + +### 3. View Your Document + ```bash npm run dev # Navigate to http://localhost:3000/docs/my-guide ``` -**Frontmatter fields:** -- `title` (required): Doc title -- `slug` (required): URL-safe identifier -- `published` (optional): Show/hide doc -- `date` (optional): Publication date -- `author` (optional): Author name (if not specified, `EMBERDOCS_DEFAULT_AUTHOR` env var is used) -- `tags` (optional): Comma-separated tags -- `order` (optional): Custom sort order in sidebar (lower numbers appear first) - -**Environment variables for branding:** -- `EMBERDOCS_DEFAULT_AUTHOR`: Default author when document frontmatter doesn't specify one -- `EMBERDOCS_COMPANY_NAME`: Company/organization name (used in headers and metadata) -- `EMBERDOCS_PRODUCT_NAME`: Product name (default: "EmberDocs", used in headers and metadata) -- `EMBERDOCS_PRIMARY_URL`: Primary URL for your company/product - --- -## Daily Progress Logging +## Configuration -### Creating a Progress Log +### Environment Variables -Each day, create `dev-docs/progress/YYYY_MM_DD.md`: +All configuration is done via environment variables in `.env.local`: -```markdown -# Progress: 2025-12-23 - -## Summary -- ✅ Created ADL (Architecture Decision Log) for design decisions -- ✅ Enhanced mvp_phase01of02.md with detailed deliverables -- ✅ Enhanced mvp_phase02of02.md with success metrics - -## Work Done -### Architecture Decisions (dev-docs/guides/ARCHITECTURE-DECISIONS.md) -- Created comprehensive ADL documenting 7 key decisions (Next.js, Tailwind, FlexSearch, etc.) -- Includes decision context, alternatives, and consequences - -### Phase 01 Plan Enhancement -- Added 9 detailed deliverables (D1.1–D1.9) with acceptance criteria -- Defined weekly milestones (Week 1–3) -- Added success metrics/KPIs table - -### Phase 02 Plan Enhancement -- Added 9 detailed deliverables (D2.1–D2.9) -- Defined weekly milestones -- Documented exit criteria (Beta readiness) - -## Open Questions -- Should we pre-generate Lighthouse reports in CI, or manual audit only? - -## Next Steps -1. Create developer quick reference guide -2. Enhance PR template with doc path linking -3. Create changelog template - -## Related PRs/Issues -- #42: Planning documentation improvements -- #39: ADL for design decisions -``` +**Content & Routing:** +- `EMBERDOCS_CONTENT_DIR` - Documentation directory (default: `docs/examples`) +- `EMBERDOCS_BASE_ROUTE` - URL prefix (default: `/docs`) -**File pattern:** `dev-docs/progress/YYYY_MM_DD.md` -**Frequency:** Daily (at end of work day or next morning) -**Link from:** Commit messages, PR description +**Branding:** +- `EMBERDOCS_THEME` - Theme: `dark` (default), `light`, or `monochrome` +- `EMBERDOCS_COMPANY_NAME` - Company/organization name +- `EMBERDOCS_PRODUCT_NAME` - Product name (default: "EmberDocs") +- `EMBERDOCS_DEFAULT_AUTHOR` - Default author for documents +- `EMBERDOCS_PRIMARY_URL` - Primary website URL +- `EMBERDOCS_LOGO_PATH` - Path to custom logo (e.g., `/logos/my-logo.png`) ---- +**Navigation:** +- `EMBERDOCS_HEADER_LINKS` - Header navigation links (JSON format) +- `EMBERDOCS_FOOTER_TEXT` - Footer text +- `EMBERDOCS_FOOTER_LINKS` - Footer links (JSON format) -## Editing Documentation +**See [Setup Guide](Setup.md) for detailed configuration options.** -### Specs & Architecture Docs (in `dev-docs/specs/` and `dev-docs/guides/`) -- **Purpose:** Developer-facing, technical details -- **Files:** `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md`, `dev-docs/specs/EMBERDOCS-API-SPEC.md`, `dev-docs/guides/ARCHITECTURE-DECISIONS.md`, etc. -- **Update when:** Making architectural decisions, changing code structure, designing new features +--- -### User Guides (in `dev-docs/`) -- **Purpose:** End-user instructions (non-developers) -- **Files:** `Setup.md`, `Deployment.md`, `Configuration.md`, etc. -- **Update when:** Adding new features, changing UI, simplifying workflows +## Customizing Sidebar Order -### Planning (in `dev-docs/planning/`) -- **Purpose:** Phase plans, roadmap, milestones -- **Files:** `mvp_phase01of02.md`, `mvp_phase02of02.md` -- **Update when:** Refining deliverables, adjusting scope, completing phases +Control sidebar order by adding an `order` field to frontmatter: -### Progress (in `dev-docs/progress/`) -- **Purpose:** Daily work logs -- **Files:** `YYYY_MM_DD_progress.md` -- **Update when:** End of each work day +```markdown +--- +title: Getting Started +order: 1 +--- +``` -**Rule:** Keep related documents cross-linked. If you change a spec, link the PR from the progress log. +**Sorting rules:** +- Items with `order` are sorted numerically (1, 2, 3...) +- Items without `order` are sorted alphabetically after ordered items +- Folders appear before documents in the same parent --- -## Git Workflow +## Building & Deploying + +### Build for Production -### Branching ```bash -# Create feature branch -git checkout -b feature/search-ranking +npm run build +``` -# Or chore/docs branch -git checkout -b chore/docs-refresh +This creates an optimized production build in `.next/` directory. -# Push to remote -git push origin feature/search-ranking -``` +### Rebuild Search Index + +If you change the content directory or add many new documents: -### Commit Messages (Imperative, Short) ```bash -# ✅ Good -git commit -m "Add FlexSearch index generation" -git commit -m "Fix color contrast in dark theme" -git commit -m "Update Phase 01 plan with deliverables" - -# ❌ Avoid -git commit -m "fixed stuff" -git commit -m "WIP: search index" +npm run build:search ``` -### PR Checklist (from `.github/PULL_REQUEST_TEMPLATE.md`) -- [ ] Summary: describe what changed and why -- [ ] Link related issues: "Fixes #42" -- [ ] Test results: "npm test passes" -- [ ] Doc updates: link paths like `dev-docs/planning/mvp_phase01of02.md` -- [ ] Screenshots: for UI changes (Loom video for complex flows) +**Note:** Search index is automatically rebuilt during `npm run build`, so you only need this for development. ---- +### Test Production Build Locally -## TypeScript Tips - -### Typed Function Exports -```typescript -// ✅ Always include return type on exports -export function parseMarkdown(content: string): ParsedDoc { - // implementation - return { frontmatter, body }; -} - -// Component with explicit props type -interface DocPageProps { - slug: string; - content: string; -} - -export default function DocPage({ slug, content }: DocPageProps) { - return
{content}
; -} - -// ❌ Avoid implicit `any` -export function parseMarkdown(content) { // ← implicit any - // ... -} +```bash +npm run build +npm start +# Visit http://localhost:3000 ``` -### Strict Mode Benefits -- Enables stricter null/undefined checking -- Catches more errors at compile time -- Better IntelliSense in editor - -Check `tsconfig.json`: `"strict": true` - --- -## Debugging +## Troubleshooting -### Browser DevTools -```typescript -// Log to browser console -console.log('Search index size:', indexData.length); -console.time('search-query'); -const results = search(query); -console.timeEnd('search-query'); -``` +**Documentation not appearing?** +- Check that files are in the correct directory (default: `docs/examples/`) +- Verify frontmatter has required `title` and `slug` fields +- Ensure files have `.md` extension +- Restart dev server after adding new files -### Build-Time Debugging -```bash -# Show Next.js build info -npm run build -- --debug +**Search not working?** +- Rebuild search index: `npm run build:search` +- Check browser console for errors +- Verify search index file exists: `public/search-index.json` -# Check bundle size -npm run build -- --analyze +**Environment variables not working?** +- Confirm `.env.local` exists (copy from `.env.example`) +- Restart dev server after changing variables +- Check variable names match exactly (case-sensitive) -# Verbose ESLint output -npm run lint -- --debug -``` +**Build errors?** +- Run `npm run build` to see detailed error messages +- Check Node.js version: `node --version` (requires 18+) +- Verify all markdown files have valid frontmatter -### Testing Specific File -```bash -npm test -- src/lib/search.test.ts -npm test -- --watch src/lib/search.test.ts -``` +**Styling issues?** +- Clear browser cache +- Check that Tailwind classes are valid +- Verify theme variable is set correctly --- -## Performance Checklist - -- [ ] Run `npm run build` and check output size (aim for < 10MB gzipped) -- [ ] Test search performance on 1000+ docs (target: < 50ms per query) -- [ ] Check Lighthouse score (`npm run build` → Vercel preview → Lighthouse tab) -- [ ] Test on slow network (DevTools → Network → "Slow 4G") -- [ ] Test on mobile device or DevTools device emulation +## Frequently Asked Questions ---- +**Q: How do I change where my documentation files are stored?** +A: Set `EMBERDOCS_CONTENT_DIR` in `.env.local`, then rebuild search index with `npm run build:search`. -## Frequently Asked Questions +**Q: Can I use a different URL prefix than `/docs`?** +A: Yes, set `EMBERDOCS_BASE_ROUTE` in `.env.local` (e.g., `/documentation` or `/help`). -**Q: Why is build time slow?** -A: Check bundle size with `npm run build`. If > 10MB, you may have added large dependencies. Use dynamic imports for heavy modules. +**Q: How do I customize the theme?** +A: Set `EMBERDOCS_THEME` to `dark`, `light`, or `monochrome` in `.env.local`. -**Q: How do I add a new npm dependency?** -A: Run `npm install `, commit `package-lock.json`, then test locally with `npm run check`. +**Q: How do I add a custom logo?** +A: Place logo in `public/` folder, then set `EMBERDOCS_LOGO_PATH=/path/to/logo.png` in `.env.local`. -**Q: Can I run tests for just one component?** -A: Yes! `npm test -- MyComponent.test.ts` +**Q: How do I control sidebar order?** +A: Add an `order` field to your markdown frontmatter. Lower numbers appear first. -**Q: What if I accidentally break types?** -A: Run `npm run typecheck` to see errors. Fix by adding type annotations or adjusting code to match expected types. +**Q: Can I hide a document from navigation?** +A: Set `published: false` in the document's frontmatter. -**Q: How do I preview a build locally?** -A: Run `npm run build && npm start` (starts production server on localhost:3000). +**Q: How do I preview the production build?** +A: Run `npm run build && npm start`, then visit `http://localhost:3000`. -**Q: Where do I ask questions?** -A: Check `dev-docs/` and `claude.md` first. Open an issue on GitHub for bugs or feature requests. +**Q: Where do I ask questions or report bugs?** +A: Open an issue on [GitHub](https://github.com/sturdy-barnacle/emberdocs/issues) or use [GitHub Discussions](https://github.com/sturdy-barnacle/emberdocs/discussions). --- @@ -429,22 +225,20 @@ A: Check `dev-docs/` and `claude.md` first. Open an issue on GitHub for bugs or | Resource | Purpose | Path | |----------|---------|------| -| **Technical Spec** | Architecture, data structures, API design | `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` | -| **Phase Plans** | Detailed deliverables & milestones | `dev-docs/planning/mvp_phase01of02.md`, `mvp_phase02of02.md` | -| **Architecture Decisions** | "Why" behind major technical choices | `dev-docs/guides/ARCHITECTURE-DECISIONS.md` | -| **Contributor Guidelines** | Code style, docs, git workflow | `AGENTS.md`, `claude.md`, `.cursorrules` | -| **Brand Guide** | Colors, typography, logos | `brand/EMBERDOCS-STYLE-GUIDE.md` | -| **User Docs** | Setup, deployment, troubleshooting | `dev-docs/` | -| **API Spec** | REST & GraphQL endpoints | `dev-docs/specs/EMBERDOCS-API-SPEC.md` | -| **Database Schema** | PostgreSQL schema, Prisma ORM | `dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md` | +| **Setup Guide** | Complete installation and configuration | `dev-docs/Setup.md` | +| **Deployment Guide** | Deploy to Vercel, Netlify, or self-hosted | `dev-docs/Deployment.md` | +| **Style Guide** | Customize themes, colors, and branding | `brand/EMBERDOCS-STYLE-GUIDE.md` | +| **Brand Guidelines** | Logo usage and brand identity | `brand/emberdocs-brand-guidelines.md` | --- ## Need Help? -1. **Check existing docs:** Most answers are in `docs/` or `dev-docs/` -2. **Review progress logs:** See what was done recently in `dev-docs/progress/` -3. **Search code:** Use GitHub search or IDE grep for patterns -4. **Ask in issues:** Open a GitHub issue or discussion -5. **Slack/Discord:** Reach out to team (if applicable) +1. **Check the guides:** [Setup Guide](Setup.md) and [Deployment Guide](Deployment.md) +2. **Search existing issues:** [GitHub Issues](https://github.com/sturdy-barnacle/emberdocs/issues) +3. **Ask the community:** [GitHub Discussions](https://github.com/sturdy-barnacle/emberdocs/discussions) +4. **Report bugs:** [Open an issue](https://github.com/sturdy-barnacle/emberdocs/issues/new) + +--- +**Want to contribute?** See [Contributing Guidelines](AGENTS.md) for development setup and workflow. diff --git a/dev-docs/Setup.md b/dev-docs/Setup.md index 8a5de44..73f058e 100644 --- a/dev-docs/Setup.md +++ b/dev-docs/Setup.md @@ -215,20 +215,34 @@ This would mean: ## Run Locally ```bash npm run dev -# or for CI parity -npm run lint && npm run typecheck && npm run test ``` -- App will serve on `http://localhost:3000` once `src/` is populated per the technical spec. -## Structure to Know -- `dev-docs/`: all developer documentation (specs, guides, planning, progress, and user guides) -- `dev-docs/specs/`: technical specifications -- `dev-docs/guides/`: development guides -- `dev-docs/planning/`: phase plans (e.g., `mvp_phase01of02.md`) -- `dev-docs/progress/`: daily logs (`YYYY_MM_DD_progress.md`) -- `docs/examples/`: example documentation files (user-facing sample docs) +The app will serve on `http://localhost:3000`. Visit that URL to see your documentation site. ## Troubleshooting -- Missing dependencies? Run `npm install`. -- Failing lint/typecheck? Ensure files follow Prettier/ESLint/TS settings in repo. -- Env errors? Confirm `.env.local` exists and required keys are set. + +**Missing dependencies?** +```bash +npm install +``` + +**Search not working?** +Rebuild the search index: +```bash +npm run build:search +``` + +**Environment variable not working?** +- Confirm `.env.local` exists (copy from `.env.example` if needed) +- Restart the dev server after changing environment variables +- Check that variable names match exactly (case-sensitive) + +**Documentation not appearing?** +- Verify your markdown files are in the correct directory (default: `docs/examples/`) +- Check that files have valid frontmatter with `title` and `slug` fields +- Ensure files have `.md` extension + +**Build errors?** +- Run `npm run build` to see detailed error messages +- Check that all required environment variables are set (if any) +- Verify Node.js version is 18 or higher: `node --version` diff --git a/dev-docs/specs/EMBERDOCS-API-SPEC.md b/dev-docs/specs/EMBERDOCS-API-SPEC.md deleted file mode 100644 index 08e4f5a..0000000 --- a/dev-docs/specs/EMBERDOCS-API-SPEC.md +++ /dev/null @@ -1,982 +0,0 @@ -# EmberDocs API Specifications - -**Version:** 1.0 -**Base URL:** `https://api.emberdocs.com/v1` -**Authentication:** Bearer token or API key - ---- - -## Overview - -The EmberDocs API provides programmatic access to documentation management, deployment, and analytics. The OSS version has no API dependencies. The premium version provides REST and GraphQL APIs for automation and integrations. - -**API Types:** -1. **Public API** - Accessible with API keys for site management -2. **Internal API** - Used by EmberDocs frontend applications -3. **Webhook API** - Receives events from git providers - ---- - -## Authentication - -### API Keys - -Create API keys in the EmberDocs dashboard. Keys are scoped to specific sites and permissions. - -```bash -# Header authentication -Authorization: Bearer ed_prod_abc123... - -# Query parameter (not recommended for production) -?api_key=ed_prod_abc123... -``` - -**Key Format:** -``` -ed_{environment}_{random} - ↓ ↓ ↓ -prefix prod/test random string - -Example: ed_prod_7k3n9x2m4p1q8w5e -``` - -**Scopes:** -- `read:docs` - Read documentation content -- `write:docs` - Create/update documentation -- `delete:docs` - Delete documentation -- `deploy` - Trigger deployments -- `read:analytics` - Access analytics data -- `manage:team` - Manage team members -- `admin` - Full access - -### OAuth 2.0 - -For third-party integrations. - -``` -GET /oauth/authorize - ?client_id=... - &redirect_uri=... - &response_type=code - &scope=read:docs write:docs -``` - ---- - -## Rate Limits - -**Free Tier:** -- 60 requests per minute -- 1,000 requests per day - -**Premium Tier:** -- 300 requests per minute -- 10,000 requests per day - -**Headers:** -``` -X-RateLimit-Limit: 300 -X-RateLimit-Remaining: 299 -X-RateLimit-Reset: 1640995200 -``` - ---- - -## Sites API - -### List Sites - -```http -GET /sites -``` - -**Response:** -```json -{ - "data": [ - { - "id": "550e8400-e29b-41d4-a716-446655440000", - "name": "My Documentation", - "slug": "my-docs", - "customDomain": "docs.example.com", - "status": "active", - "deploymentStatus": "deployed", - "lastDeployedAt": "2024-12-06T10:30:00Z", - "createdAt": "2024-11-01T08:00:00Z", - "urls": { - "emberdocs": "https://my-docs.emberdocs.com", - "custom": "https://docs.example.com" - } - } - ], - "pagination": { - "page": 1, - "perPage": 20, - "total": 42, - "pages": 3 - } -} -``` - -### Get Site - -```http -GET /sites/:id -``` - -**Response:** -```json -{ - "data": { - "id": "550e8400-e29b-41d4-a716-446655440000", - "name": "My Documentation", - "slug": "my-docs", - "customDomain": "docs.example.com", - "git": { - "provider": "github", - "repoUrl": "https://github.com/user/repo", - "branch": "main" - }, - "config": { - "docsPath": "./docs", - "theme": { - "colors": { - "primary": "#8B5CF6" - } - } - }, - "status": "active", - "deploymentStatus": "deployed", - "lastDeployedAt": "2024-12-06T10:30:00Z", - "lastBuildDurationMs": 4523, - "analytics": { - "enabled": true, - "searchAnalytics": true - }, - "createdAt": "2024-11-01T08:00:00Z", - "updatedAt": "2024-12-06T10:30:00Z" - } -} -``` - -### Create Site - -```http -POST /sites -``` - -**Request:** -```json -{ - "name": "My Documentation", - "slug": "my-docs", - "gitProvider": "github", - "gitRepoUrl": "https://github.com/user/repo", - "gitBranch": "main", - "docsPath": "./docs", - "config": { - "theme": { - "colors": { - "primary": "#8B5CF6" - } - } - } -} -``` - -**Response:** -```json -{ - "data": { - "id": "550e8400-e29b-41d4-a716-446655440000", - "name": "My Documentation", - "slug": "my-docs", - "status": "pending", - "webhookUrl": "https://api.emberdocs.com/v1/webhooks/550e8400-e29b-41d4-a716-446655440000", - "webhookSecret": "whsec_abc123..." - } -} -``` - -### Update Site - -```http -PATCH /sites/:id -``` - -**Request:** -```json -{ - "name": "Updated Documentation", - "customDomain": "docs.example.com", - "config": { - "theme": { - "colors": { - "primary": "#10B981" - } - } - } -} -``` - -### Delete Site - -```http -DELETE /sites/:id -``` - -**Response:** -```json -{ - "data": { - "id": "550e8400-e29b-41d4-a716-446655440000", - "status": "deleted", - "deletedAt": "2024-12-06T11:00:00Z" - } -} -``` - ---- - -## Deployments API - -### List Deployments - -```http -GET /sites/:siteId/deployments -``` - -**Query Parameters:** -- `status` - Filter by status (pending, building, success, failed) -- `limit` - Results per page (default: 20, max: 100) -- `page` - Page number - -**Response:** -```json -{ - "data": [ - { - "id": "deploy_123", - "status": "success", - "triggerType": "webhook", - "git": { - "commitSha": "abc123def456", - "commitMessage": "Update documentation", - "branch": "main" - }, - "metrics": { - "buildDurationMs": 4523, - "pagesBuilt": 42, - "assetsSizeBytes": 1048576 - }, - "startedAt": "2024-12-06T10:25:00Z", - "completedAt": "2024-12-06T10:30:00Z" - } - ] -} -``` - -### Get Deployment - -```http -GET /sites/:siteId/deployments/:id -``` - -**Response:** -```json -{ - "data": { - "id": "deploy_123", - "status": "success", - "triggerType": "webhook", - "git": { - "commitSha": "abc123def456", - "commitMessage": "Update documentation", - "branch": "main" - }, - "buildLog": "Building documentation...\n✓ Parsed 42 markdown files\n✓ Generated navigation\n✓ Built search index\n✓ Deployment complete", - "metrics": { - "buildDurationMs": 4523, - "pagesBuilt": 42, - "assetsSizeBytes": 1048576 - }, - "startedAt": "2024-12-06T10:25:00Z", - "completedAt": "2024-12-06T10:30:00Z" - } -} -``` - -### Trigger Deployment - -```http -POST /sites/:siteId/deployments -``` - -**Request:** -```json -{ - "branch": "main", - "clearCache": false -} -``` - -**Response:** -```json -{ - "data": { - "id": "deploy_124", - "status": "pending", - "triggerType": "manual", - "startedAt": "2024-12-06T11:00:00Z" - } -} -``` - -### Cancel Deployment - -```http -POST /sites/:siteId/deployments/:id/cancel -``` - ---- - -## Content API - -### List Pages - -```http -GET /sites/:siteId/pages -``` - -**Response:** -```json -{ - "data": [ - { - "path": "/getting-started", - "title": "Getting Started", - "category": "Documentation", - "updatedAt": "2024-12-05T14:30:00Z", - "url": "https://my-docs.emberdocs.com/getting-started" - } - ] -} -``` - -### Get Page - -```http -GET /sites/:siteId/pages/:path -``` - -**Example:** -```http -GET /sites/550e8400.../pages/getting-started -``` - -**Response:** -```json -{ - "data": { - "path": "/getting-started", - "title": "Getting Started", - "description": "Learn how to get started with EmberDocs", - "content": "# Getting Started\n\nWelcome to...", - "metadata": { - "category": "Documentation", - "tags": ["guide", "beginner"], - "author": "John Doe" - }, - "readingTime": 5, - "updatedAt": "2024-12-05T14:30:00Z" - } -} -``` - -### Search Pages - -```http -GET /sites/:siteId/pages/search?q=authentication -``` - -**Response:** -```json -{ - "data": { - "query": "authentication", - "results": [ - { - "path": "/api/authentication", - "title": "Authentication", - "excerpt": "Learn how to authenticate API requests using API keys or OAuth...", - "score": 0.95 - } - ], - "total": 3, - "searchDurationMs": 45 - } -} -``` - ---- - -## Analytics API - -### Get Overview - -```http -GET /sites/:siteId/analytics/overview -``` - -**Query Parameters:** -- `from` - Start date (ISO 8601) -- `to` - End date (ISO 8601) -- `interval` - Grouping (hour, day, week, month) - -**Response:** -```json -{ - "data": { - "period": { - "from": "2024-11-01T00:00:00Z", - "to": "2024-12-01T00:00:00Z" - }, - "pageViews": { - "total": 15420, - "unique": 8234, - "trend": 12.5 - }, - "visitors": { - "total": 5432, - "returning": 2156, - "new": 3276 - }, - "averageTimeOnPage": 180, - "bounceRate": 0.32, - "topPages": [ - { - "path": "/getting-started", - "views": 2340, - "uniqueVisitors": 1876 - } - ], - "topReferrers": [ - { - "domain": "google.com", - "visits": 1234 - } - ], - "devices": { - "desktop": 8234, - "mobile": 6012, - "tablet": 1174 - } - } -} -``` - -### Get Page Analytics - -```http -GET /sites/:siteId/analytics/pages/:path -``` - -**Response:** -```json -{ - "data": { - "path": "/getting-started", - "title": "Getting Started", - "metrics": { - "pageViews": 2340, - "uniqueVisitors": 1876, - "averageTimeOnPage": 245, - "scrollDepth": { - "0-25": 234, - "25-50": 543, - "50-75": 892, - "75-100": 671 - } - }, - "timeSeries": [ - { - "date": "2024-11-01", - "views": 123 - } - ], - "referrers": [ - { - "domain": "google.com", - "visits": 342 - } - ] - } -} -``` - -### Get Search Analytics - -```http -GET /sites/:siteId/analytics/search -``` - -**Query Parameters:** -- `from` - Start date -- `to` - End date -- `limit` - Number of results - -**Response:** -```json -{ - "data": { - "topQueries": [ - { - "query": "authentication", - "count": 234, - "avgResultsCount": 5.2, - "clickThroughRate": 0.76 - } - ], - "noResultQueries": [ - { - "query": "deployment hooks", - "count": 12 - } - ], - "totalSearches": 1543, - "averageSearchDuration": 67 - } -} -``` - ---- - -## Team API - -### List Team Members - -```http -GET /sites/:siteId/team -``` - -**Response:** -```json -{ - "data": [ - { - "id": "member_123", - "user": { - "id": "user_456", - "name": "John Doe", - "email": "john@example.com", - "avatarUrl": "https://..." - }, - "role": "admin", - "status": "active", - "invitedAt": "2024-11-01T08:00:00Z", - "acceptedAt": "2024-11-01T09:15:00Z" - } - ] -} -``` - -### Invite Team Member - -```http -POST /sites/:siteId/team -``` - -**Request:** -```json -{ - "email": "jane@example.com", - "role": "editor" -} -``` - -**Response:** -```json -{ - "data": { - "id": "member_124", - "email": "jane@example.com", - "role": "editor", - "status": "pending", - "invitedAt": "2024-12-06T11:00:00Z", - "inviteUrl": "https://emberdocs.com/invite/abc123..." - } -} -``` - -### Update Team Member - -```http -PATCH /sites/:siteId/team/:memberId -``` - -**Request:** -```json -{ - "role": "admin" -} -``` - -### Remove Team Member - -```http -DELETE /sites/:siteId/team/:memberId -``` - ---- - -## Webhooks API - -### Configure Webhook - -```http -POST /sites/:siteId/webhooks -``` - -**Request:** -```json -{ - "url": "https://example.com/webhook", - "events": ["deployment.started", "deployment.completed", "deployment.failed"], - "secret": "your_webhook_secret" -} -``` - -**Response:** -```json -{ - "data": { - "id": "webhook_123", - "url": "https://example.com/webhook", - "events": ["deployment.started", "deployment.completed"], - "status": "active", - "createdAt": "2024-12-06T11:00:00Z" - } -} -``` - -### Webhook Events - -**Deployment Started:** -```json -{ - "event": "deployment.started", - "timestamp": "2024-12-06T10:25:00Z", - "data": { - "siteId": "550e8400-e29b-41d4-a716-446655440000", - "deploymentId": "deploy_123", - "git": { - "commitSha": "abc123", - "branch": "main" - } - } -} -``` - -**Deployment Completed:** -```json -{ - "event": "deployment.completed", - "timestamp": "2024-12-06T10:30:00Z", - "data": { - "siteId": "550e8400-e29b-41d4-a716-446655440000", - "deploymentId": "deploy_123", - "status": "success", - "metrics": { - "buildDurationMs": 4523, - "pagesBuilt": 42 - }, - "url": "https://my-docs.emberdocs.com" - } -} -``` - -### Webhook Signature Verification - -```javascript -const crypto = require('crypto'); - -function verifyWebhook(payload, signature, secret) { - const hmac = crypto.createHmac('sha256', secret); - const digest = hmac.update(payload).digest('hex'); - return crypto.timingSafeEqual( - Buffer.from(signature), - Buffer.from(digest) - ); -} - -// Express middleware -app.post('/webhook', (req, res) => { - const signature = req.headers['x-emberdocs-signature']; - const payload = JSON.stringify(req.body); - - if (!verifyWebhook(payload, signature, WEBHOOK_SECRET)) { - return res.status(401).send('Invalid signature'); - } - - // Process webhook - res.status(200).send('OK'); -}); -``` - ---- - -## Git Provider Webhooks - -### GitHub - -```http -POST /webhooks/:siteId -``` - -**Headers:** -``` -X-GitHub-Event: push -X-Hub-Signature-256: sha256=... -Content-Type: application/json -``` - -**Payload:** -```json -{ - "ref": "refs/heads/main", - "commits": [ - { - "id": "abc123def456", - "message": "Update documentation" - } - ] -} -``` - -### GitLab - -```http -POST /webhooks/:siteId -``` - -**Headers:** -``` -X-Gitlab-Event: Push Hook -X-Gitlab-Token: ... -``` - -### Bitbucket - -```http -POST /webhooks/:siteId -``` - -**Headers:** -``` -X-Event-Key: repo:push -``` - ---- - -## Error Responses - -### Error Format - -```json -{ - "error": { - "code": "RESOURCE_NOT_FOUND", - "message": "Site with ID '123' not found", - "details": { - "siteId": "123" - }, - "requestId": "req_abc123" - } -} -``` - -### Common Error Codes - -| Code | HTTP Status | Description | -|------|-------------|-------------| -| `UNAUTHORIZED` | 401 | Invalid or missing authentication | -| `FORBIDDEN` | 403 | Insufficient permissions | -| `RESOURCE_NOT_FOUND` | 404 | Resource does not exist | -| `VALIDATION_ERROR` | 422 | Invalid request data | -| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests | -| `INTERNAL_ERROR` | 500 | Server error | - ---- - -## SDK Examples - -### JavaScript/TypeScript - -```typescript -import { EmberDocs } from '@emberdocs/sdk'; - -const client = new EmberDocs({ - apiKey: process.env.EMBERDOCS_API_KEY, -}); - -// List sites -const sites = await client.sites.list(); - -// Get site -const site = await client.sites.get('site_id'); - -// Trigger deployment -const deployment = await client.deployments.create('site_id', { - branch: 'main', -}); - -// Get analytics -const analytics = await client.analytics.getOverview('site_id', { - from: '2024-11-01', - to: '2024-12-01', -}); -``` - -### Python - -```python -from emberdocs import EmberDocs - -client = EmberDocs(api_key=os.environ['EMBERDOCS_API_KEY']) - -# List sites -sites = client.sites.list() - -# Get site -site = client.sites.get('site_id') - -# Trigger deployment -deployment = client.deployments.create( - site_id='site_id', - branch='main' -) - -# Get analytics -analytics = client.analytics.get_overview( - site_id='site_id', - from_date='2024-11-01', - to_date='2024-12-01' -) -``` - -### cURL - -```bash -# List sites -curl -H "Authorization: Bearer $API_KEY" \ - https://api.emberdocs.com/v1/sites - -# Get site -curl -H "Authorization: Bearer $API_KEY" \ - https://api.emberdocs.com/v1/sites/550e8400... - -# Trigger deployment -curl -X POST \ - -H "Authorization: Bearer $API_KEY" \ - -H "Content-Type: application/json" \ - -d '{"branch":"main"}' \ - https://api.emberdocs.com/v1/sites/550e8400.../deployments - -# Get analytics -curl -H "Authorization: Bearer $API_KEY" \ - "https://api.emberdocs.com/v1/sites/550e8400.../analytics/overview?from=2024-11-01&to=2024-12-01" -``` - ---- - -## GraphQL API (Premium) - -### Endpoint - -``` -POST https://api.emberdocs.com/v1/graphql -``` - -### Example Query - -```graphql -query GetSite($siteId: ID!) { - site(id: $siteId) { - id - name - slug - customDomain - deploymentStatus - lastDeployedAt - - deployments(limit: 5) { - id - status - startedAt - completedAt - git { - commitSha - commitMessage - } - } - - analytics(from: "2024-11-01", to: "2024-12-01") { - pageViews { - total - unique - trend - } - topPages { - path - views - } - } - } -} -``` - -### Example Mutation - -```graphql -mutation TriggerDeployment($siteId: ID!, $branch: String) { - triggerDeployment(siteId: $siteId, branch: $branch) { - id - status - startedAt - } -} -``` - ---- - -## API Versioning - -**Versioning Strategy:** -- URL versioning (`/v1`, `/v2`) -- Backward compatibility within major versions -- Deprecation notices 6 months before removal -- Version lifecycle: Current, Deprecated, Sunset - -**Version Headers:** -``` -X-API-Version: 1.0 -X-Deprecated: false -``` - -**Deprecation Notice:** -```json -{ - "data": {...}, - "warnings": [ - { - "type": "deprecation", - "message": "This endpoint will be removed on 2025-06-01", - "replacement": "/v2/sites" - } - ] -} -``` - ---- - -This API specification covers all programmatic access patterns for EmberDocs premium features. diff --git a/dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md b/dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md deleted file mode 100644 index 3ef5d5d..0000000 --- a/dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md +++ /dev/null @@ -1,917 +0,0 @@ -# EmberDocs Database Schema - -**Version:** 1.0 -**Database:** PostgreSQL 14+ -**ORM:** Prisma (recommended) - ---- - -## Overview - -The database schema supports the premium hosted version of EmberDocs. The OSS version is fully static and requires no database. Premium features requiring persistent storage include: - -- User accounts and authentication -- Hosted documentation sites -- Team collaboration -- Advanced analytics -- API access tokens -- Billing and subscriptions - -**Design Principles:** -- Multi-tenancy support (one DB, many sites) -- Audit trails for compliance -- Soft deletes for data recovery -- Timestamps on all tables -- UUID primary keys for security - ---- - -## Schema Diagram - -``` -┌─────────────┐ -│ users │──┐ -└─────────────┘ │ - │ -┌─────────────┐ │ ┌──────────────┐ -│ sites │←─┴──│ team_members │ -└─────────────┘ └──────────────┘ - │ - ├──→ ┌────────────────┐ - │ │ deployments │ - │ └────────────────┘ - │ - ├──→ ┌────────────────┐ - │ │ page_views │ - │ └────────────────┘ - │ - ├──→ ┌────────────────┐ - │ │ search_queries│ - │ └────────────────┘ - │ - └──→ ┌────────────────┐ - │ api_tokens │ - └────────────────┘ - -┌─────────────────┐ -│ subscriptions │ -└─────────────────┘ - │ - └──→ ┌────────────────┐ - │ invoices │ - └────────────────┘ -``` - ---- - -## Table Definitions - -### `users` - -Stores user account information. - -```sql -CREATE TABLE users ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - email VARCHAR(255) UNIQUE NOT NULL, - email_verified BOOLEAN DEFAULT FALSE, - name VARCHAR(255), - avatar_url TEXT, - password_hash VARCHAR(255), -- Only for email/password auth - - -- OAuth fields - oauth_provider VARCHAR(50), -- 'github', 'google', etc. - oauth_id VARCHAR(255), - - -- Account status - status VARCHAR(20) DEFAULT 'active', -- 'active', 'suspended', 'deleted' - role VARCHAR(20) DEFAULT 'user', -- 'user', 'admin' - - -- Timestamps - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW(), - last_login_at TIMESTAMP, - deleted_at TIMESTAMP, - - -- Constraints - CONSTRAINT valid_email CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$'), - CONSTRAINT valid_status CHECK (status IN ('active', 'suspended', 'deleted')), - CONSTRAINT valid_role CHECK (role IN ('user', 'admin')) -); - -CREATE INDEX idx_users_email ON users(email); -CREATE INDEX idx_users_oauth ON users(oauth_provider, oauth_id); -CREATE INDEX idx_users_status ON users(status) WHERE deleted_at IS NULL; -``` - -### `sites` - -Documentation sites hosted on EmberDocs premium. - -```sql -CREATE TABLE sites ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - owner_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, - - -- Site identity - name VARCHAR(255) NOT NULL, - slug VARCHAR(100) UNIQUE NOT NULL, -- subdomain: slug.emberdocs.com - custom_domain VARCHAR(255), -- Optional custom domain - - -- Git integration - git_provider VARCHAR(50), -- 'github', 'gitlab', 'bitbucket' - git_repo_url TEXT, - git_branch VARCHAR(100) DEFAULT 'main', - git_webhook_secret VARCHAR(255), - - -- Build configuration - docs_path VARCHAR(255) DEFAULT './docs', - build_command TEXT, - - -- Site settings (JSON for flexibility) - config JSONB DEFAULT '{}', - - -- Deployment - deployment_status VARCHAR(50) DEFAULT 'pending', -- 'pending', 'building', 'deployed', 'failed' - last_deployed_at TIMESTAMP, - last_build_duration_ms INTEGER, - - -- Analytics settings - analytics_enabled BOOLEAN DEFAULT TRUE, - search_analytics_enabled BOOLEAN DEFAULT TRUE, - - -- Status - status VARCHAR(20) DEFAULT 'active', -- 'active', 'paused', 'deleted' - - -- Timestamps - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW(), - deleted_at TIMESTAMP, - - -- Constraints - CONSTRAINT valid_slug CHECK (slug ~* '^[a-z0-9-]+$'), - CONSTRAINT valid_git_provider CHECK (git_provider IN ('github', 'gitlab', 'bitbucket') OR git_provider IS NULL), - CONSTRAINT valid_deployment_status CHECK (deployment_status IN ('pending', 'building', 'deployed', 'failed')) -); - -CREATE INDEX idx_sites_owner ON sites(owner_id) WHERE deleted_at IS NULL; -CREATE INDEX idx_sites_slug ON sites(slug) WHERE deleted_at IS NULL; -CREATE INDEX idx_sites_custom_domain ON sites(custom_domain) WHERE deleted_at IS NULL; -CREATE INDEX idx_sites_status ON sites(status, deployment_status); -``` - -### `team_members` - -Team collaboration on sites. - -```sql -CREATE TABLE team_members ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - site_id UUID NOT NULL REFERENCES sites(id) ON DELETE CASCADE, - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, - - -- Role and permissions - role VARCHAR(20) NOT NULL, -- 'owner', 'admin', 'editor', 'viewer' - permissions JSONB DEFAULT '{}', -- Custom permissions if needed - - -- Invitation - invited_by UUID REFERENCES users(id), - invited_at TIMESTAMP DEFAULT NOW(), - accepted_at TIMESTAMP, - - -- Status - status VARCHAR(20) DEFAULT 'active', -- 'active', 'pending', 'removed' - - -- Timestamps - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW(), - - -- Constraints - UNIQUE(site_id, user_id), - CONSTRAINT valid_role CHECK (role IN ('owner', 'admin', 'editor', 'viewer')), - CONSTRAINT valid_status CHECK (status IN ('active', 'pending', 'removed')) -); - -CREATE INDEX idx_team_members_site ON team_members(site_id, status); -CREATE INDEX idx_team_members_user ON team_members(user_id, status); -``` - -### `deployments` - -Deployment history and logs. - -```sql -CREATE TABLE deployments ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - site_id UUID NOT NULL REFERENCES sites(id) ON DELETE CASCADE, - - -- Trigger - triggered_by UUID REFERENCES users(id), -- NULL for webhook triggers - trigger_type VARCHAR(50) NOT NULL, -- 'manual', 'webhook', 'schedule' - - -- Git information - commit_sha VARCHAR(40), - commit_message TEXT, - branch VARCHAR(100), - - -- Build info - status VARCHAR(20) NOT NULL, -- 'pending', 'building', 'success', 'failed', 'cancelled' - build_log TEXT, - error_message TEXT, - - -- Performance metrics - build_duration_ms INTEGER, - pages_built INTEGER, - assets_size_bytes BIGINT, - - -- Timestamps - started_at TIMESTAMP DEFAULT NOW(), - completed_at TIMESTAMP, - - -- Constraints - CONSTRAINT valid_trigger_type CHECK (trigger_type IN ('manual', 'webhook', 'schedule')), - CONSTRAINT valid_status CHECK (status IN ('pending', 'building', 'success', 'failed', 'cancelled')) -); - -CREATE INDEX idx_deployments_site ON deployments(site_id, started_at DESC); -CREATE INDEX idx_deployments_status ON deployments(status, started_at DESC); -``` - -### `page_views` - -Analytics for documentation page views. - -```sql -CREATE TABLE page_views ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - site_id UUID NOT NULL REFERENCES sites(id) ON DELETE CASCADE, - - -- Page information - page_path VARCHAR(500) NOT NULL, - page_title VARCHAR(500), - - -- Session tracking (privacy-friendly) - session_hash VARCHAR(64), -- Hashed IP + User Agent (daily rotation) - - -- Referrer - referrer_domain VARCHAR(255), - referrer_path TEXT, - utm_source VARCHAR(100), - utm_medium VARCHAR(100), - utm_campaign VARCHAR(100), - - -- Device info - device_type VARCHAR(20), -- 'desktop', 'mobile', 'tablet' - browser VARCHAR(50), - os VARCHAR(50), - - -- Geographic (country-level only) - country_code CHAR(2), - - -- Engagement metrics - time_on_page_seconds INTEGER, - scroll_depth_percent INTEGER, - - -- Timestamp - viewed_at TIMESTAMP DEFAULT NOW(), - - -- Constraints - CONSTRAINT valid_device_type CHECK (device_type IN ('desktop', 'mobile', 'tablet')) -); - --- Partitioned by month for performance -CREATE TABLE page_views_2024_12 PARTITION OF page_views - FOR VALUES FROM ('2024-12-01') TO ('2025-01-01'); - -CREATE INDEX idx_page_views_site_date ON page_views(site_id, viewed_at DESC); -CREATE INDEX idx_page_views_path ON page_views(site_id, page_path, viewed_at DESC); -``` - -### `search_queries` - -Search analytics (privacy-friendly). - -```sql -CREATE TABLE search_queries ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - site_id UUID NOT NULL REFERENCES sites(id) ON DELETE CASCADE, - - -- Query information - query_text VARCHAR(500) NOT NULL, - results_count INTEGER, - - -- User action - clicked_result_path VARCHAR(500), -- Which result was clicked - clicked_position INTEGER, -- Position in results - - -- Session (privacy-friendly) - session_hash VARCHAR(64), - - -- Performance - search_duration_ms INTEGER, - - -- Timestamp - searched_at TIMESTAMP DEFAULT NOW() -); - -CREATE INDEX idx_search_queries_site_date ON search_queries(site_id, searched_at DESC); -CREATE INDEX idx_search_queries_text ON search_queries(site_id, query_text, searched_at DESC); -``` - -### `api_tokens` - -API access tokens for programmatic access. - -```sql -CREATE TABLE api_tokens ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - site_id UUID NOT NULL REFERENCES sites(id) ON DELETE CASCADE, - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, - - -- Token - name VARCHAR(255) NOT NULL, - token_hash VARCHAR(255) UNIQUE NOT NULL, -- Never store plaintext - token_prefix VARCHAR(10) NOT NULL, -- Show user: "ed_prod_abc..." - - -- Permissions - scopes TEXT[] DEFAULT '{}', -- ['read:docs', 'write:docs', 'deploy'] - - -- Usage tracking - last_used_at TIMESTAMP, - usage_count INTEGER DEFAULT 0, - - -- Expiration - expires_at TIMESTAMP, - - -- Status - status VARCHAR(20) DEFAULT 'active', -- 'active', 'revoked' - - -- Timestamps - created_at TIMESTAMP DEFAULT NOW(), - revoked_at TIMESTAMP, - - -- Constraints - CONSTRAINT valid_status CHECK (status IN ('active', 'revoked')) -); - -CREATE INDEX idx_api_tokens_site ON api_tokens(site_id, status); -CREATE INDEX idx_api_tokens_user ON api_tokens(user_id, status); -CREATE INDEX idx_api_tokens_hash ON api_tokens(token_hash) WHERE status = 'active'; -``` - -### `subscriptions` - -Premium subscriptions and billing. - -```sql -CREATE TABLE subscriptions ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, - - -- Plan details - plan_type VARCHAR(50) NOT NULL, -- 'hobby', 'pro', 'team', 'enterprise' - billing_interval VARCHAR(20) NOT NULL, -- 'monthly', 'yearly' - - -- Pricing - amount_cents INTEGER NOT NULL, - currency VARCHAR(3) DEFAULT 'USD', - - -- Stripe integration - stripe_customer_id VARCHAR(255), - stripe_subscription_id VARCHAR(255), - stripe_payment_method_id VARCHAR(255), - - -- Limits - max_sites INTEGER, - max_page_views_monthly INTEGER, - max_team_members INTEGER, - - -- Status - status VARCHAR(20) NOT NULL, -- 'active', 'trialing', 'past_due', 'cancelled', 'expired' - - -- Trial - trial_ends_at TIMESTAMP, - - -- Billing dates - current_period_start TIMESTAMP, - current_period_end TIMESTAMP, - cancel_at_period_end BOOLEAN DEFAULT FALSE, - cancelled_at TIMESTAMP, - - -- Timestamps - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW(), - - -- Constraints - CONSTRAINT valid_plan_type CHECK (plan_type IN ('hobby', 'pro', 'team', 'enterprise')), - CONSTRAINT valid_billing_interval CHECK (billing_interval IN ('monthly', 'yearly')), - CONSTRAINT valid_status CHECK (status IN ('active', 'trialing', 'past_due', 'cancelled', 'expired')) -); - -CREATE INDEX idx_subscriptions_user ON subscriptions(user_id, status); -CREATE INDEX idx_subscriptions_stripe ON subscriptions(stripe_subscription_id); -CREATE INDEX idx_subscriptions_status ON subscriptions(status, current_period_end); -``` - -### `invoices` - -Billing invoices. - -```sql -CREATE TABLE invoices ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - subscription_id UUID NOT NULL REFERENCES subscriptions(id) ON DELETE CASCADE, - user_id UUID NOT NULL REFERENCES users(id), - - -- Invoice details - invoice_number VARCHAR(50) UNIQUE NOT NULL, - amount_cents INTEGER NOT NULL, - currency VARCHAR(3) DEFAULT 'USD', - - -- Stripe - stripe_invoice_id VARCHAR(255), - stripe_payment_intent_id VARCHAR(255), - - -- Status - status VARCHAR(20) NOT NULL, -- 'draft', 'open', 'paid', 'void', 'uncollectible' - paid_at TIMESTAMP, - - -- Dates - period_start TIMESTAMP NOT NULL, - period_end TIMESTAMP NOT NULL, - due_date TIMESTAMP, - - -- PDF - pdf_url TEXT, - - -- Timestamps - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW(), - - -- Constraints - CONSTRAINT valid_status CHECK (status IN ('draft', 'open', 'paid', 'void', 'uncollectible')) -); - -CREATE INDEX idx_invoices_subscription ON invoices(subscription_id, created_at DESC); -CREATE INDEX idx_invoices_user ON invoices(user_id, created_at DESC); -CREATE INDEX idx_invoices_status ON invoices(status, due_date); -``` - -### `audit_logs` - -Audit trail for compliance. - -```sql -CREATE TABLE audit_logs ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - - -- Actor - user_id UUID REFERENCES users(id), - ip_address INET, - user_agent TEXT, - - -- Action - action VARCHAR(100) NOT NULL, -- 'site.created', 'deployment.triggered', etc. - resource_type VARCHAR(50), -- 'site', 'deployment', 'user' - resource_id UUID, - - -- Changes - old_values JSONB, - new_values JSONB, - - -- Context - metadata JSONB DEFAULT '{}', - - -- Timestamp - created_at TIMESTAMP DEFAULT NOW() -); - --- Partitioned by month -CREATE TABLE audit_logs_2024_12 PARTITION OF audit_logs - FOR VALUES FROM ('2024-12-01') TO ('2025-01-01'); - -CREATE INDEX idx_audit_logs_user ON audit_logs(user_id, created_at DESC); -CREATE INDEX idx_audit_logs_resource ON audit_logs(resource_type, resource_id, created_at DESC); -CREATE INDEX idx_audit_logs_action ON audit_logs(action, created_at DESC); -``` - ---- - -## Prisma Schema - -```prisma -// schema.prisma - -generator client { - provider = "prisma-client-js" -} - -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") -} - -model User { - id String @id @default(uuid()) - email String @unique - emailVerified Boolean @default(false) @map("email_verified") - name String? - avatarUrl String? @map("avatar_url") - passwordHash String? @map("password_hash") - - oauthProvider String? @map("oauth_provider") - oauthId String? @map("oauth_id") - - status String @default("active") - role String @default("user") - - createdAt DateTime @default(now()) @map("created_at") - updatedAt DateTime @updatedAt @map("updated_at") - lastLoginAt DateTime? @map("last_login_at") - deletedAt DateTime? @map("deleted_at") - - sites Site[] - teamMembers TeamMember[] - deployments Deployment[] - apiTokens ApiToken[] - subscriptions Subscription[] - invoices Invoice[] - auditLogs AuditLog[] - - @@map("users") -} - -model Site { - id String @id @default(uuid()) - ownerId String @map("owner_id") - owner User @relation(fields: [ownerId], references: [id], onDelete: Cascade) - - name String - slug String @unique - customDomain String? @map("custom_domain") - - gitProvider String? @map("git_provider") - gitRepoUrl String? @map("git_repo_url") - gitBranch String @default("main") @map("git_branch") - gitWebhookSecret String? @map("git_webhook_secret") - - docsPath String @default("./docs") @map("docs_path") - buildCommand String? @map("build_command") - - config Json @default("{}") - - deploymentStatus String @default("pending") @map("deployment_status") - lastDeployedAt DateTime? @map("last_deployed_at") - lastBuildDurationMs Int? @map("last_build_duration_ms") - - analyticsEnabled Boolean @default(true) @map("analytics_enabled") - searchAnalyticsEnabled Boolean @default(true) @map("search_analytics_enabled") - - status String @default("active") - - createdAt DateTime @default(now()) @map("created_at") - updatedAt DateTime @updatedAt @map("updated_at") - deletedAt DateTime? @map("deleted_at") - - teamMembers TeamMember[] - deployments Deployment[] - pageViews PageView[] - searchQueries SearchQuery[] - apiTokens ApiToken[] - - @@map("sites") -} - -model TeamMember { - id String @id @default(uuid()) - siteId String @map("site_id") - site Site @relation(fields: [siteId], references: [id], onDelete: Cascade) - userId String @map("user_id") - user User @relation(fields: [userId], references: [id], onDelete: Cascade) - - role String - permissions Json @default("{}") - - invitedBy String? @map("invited_by") - invitedAt DateTime @default(now()) @map("invited_at") - acceptedAt DateTime? @map("accepted_at") - - status String @default("active") - - createdAt DateTime @default(now()) @map("created_at") - updatedAt DateTime @updatedAt @map("updated_at") - - @@unique([siteId, userId]) - @@map("team_members") -} - -model Deployment { - id String @id @default(uuid()) - siteId String @map("site_id") - site Site @relation(fields: [siteId], references: [id], onDelete: Cascade) - - triggeredBy String? @map("triggered_by") - trigger User? @relation(fields: [triggeredBy], references: [id]) - triggerType String @map("trigger_type") - - commitSha String? @map("commit_sha") - commitMessage String? @map("commit_message") - branch String? - - status String - buildLog String? @map("build_log") - errorMessage String? @map("error_message") - - buildDurationMs Int? @map("build_duration_ms") - pagesBuilt Int? @map("pages_built") - assetsSizeBytes BigInt? @map("assets_size_bytes") - - startedAt DateTime @default(now()) @map("started_at") - completedAt DateTime? @map("completed_at") - - @@map("deployments") -} - -model PageView { - id String @id @default(uuid()) - siteId String @map("site_id") - site Site @relation(fields: [siteId], references: [id], onDelete: Cascade) - - pagePath String @map("page_path") - pageTitle String? @map("page_title") - - sessionHash String? @map("session_hash") - - referrerDomain String? @map("referrer_domain") - referrerPath String? @map("referrer_path") - utmSource String? @map("utm_source") - utmMedium String? @map("utm_medium") - utmCampaign String? @map("utm_campaign") - - deviceType String? @map("device_type") - browser String? - os String? - - countryCode String? @map("country_code") - - timeOnPageSeconds Int? @map("time_on_page_seconds") - scrollDepthPercent Int? @map("scroll_depth_percent") - - viewedAt DateTime @default(now()) @map("viewed_at") - - @@map("page_views") -} - -model SearchQuery { - id String @id @default(uuid()) - siteId String @map("site_id") - site Site @relation(fields: [siteId], references: [id], onDelete: Cascade) - - queryText String @map("query_text") - resultsCount Int? @map("results_count") - - clickedResultPath String? @map("clicked_result_path") - clickedPosition Int? @map("clicked_position") - - sessionHash String? @map("session_hash") - - searchDurationMs Int? @map("search_duration_ms") - - searchedAt DateTime @default(now()) @map("searched_at") - - @@map("search_queries") -} - -model ApiToken { - id String @id @default(uuid()) - siteId String @map("site_id") - site Site @relation(fields: [siteId], references: [id], onDelete: Cascade) - userId String @map("user_id") - user User @relation(fields: [userId], references: [id], onDelete: Cascade) - - name String - tokenHash String @unique @map("token_hash") - tokenPrefix String @map("token_prefix") - - scopes String[] @default([]) - - lastUsedAt DateTime? @map("last_used_at") - usageCount Int @default(0) @map("usage_count") - - expiresAt DateTime? @map("expires_at") - - status String @default("active") - - createdAt DateTime @default(now()) @map("created_at") - revokedAt DateTime? @map("revoked_at") - - @@map("api_tokens") -} - -model Subscription { - id String @id @default(uuid()) - userId String @map("user_id") - user User @relation(fields: [userId], references: [id], onDelete: Cascade) - - planType String @map("plan_type") - billingInterval String @map("billing_interval") - - amountCents Int @map("amount_cents") - currency String @default("USD") - - stripeCustomerId String? @map("stripe_customer_id") - stripeSubscriptionId String? @map("stripe_subscription_id") - stripePaymentMethodId String? @map("stripe_payment_method_id") - - maxSites Int? @map("max_sites") - maxPageViewsMonthly Int? @map("max_page_views_monthly") - maxTeamMembers Int? @map("max_team_members") - - status String - - trialEndsAt DateTime? @map("trial_ends_at") - - currentPeriodStart DateTime? @map("current_period_start") - currentPeriodEnd DateTime? @map("current_period_end") - cancelAtPeriodEnd Boolean @default(false) @map("cancel_at_period_end") - cancelledAt DateTime? @map("cancelled_at") - - createdAt DateTime @default(now()) @map("created_at") - updatedAt DateTime @updatedAt @map("updated_at") - - invoices Invoice[] - - @@map("subscriptions") -} - -model Invoice { - id String @id @default(uuid()) - subscriptionId String @map("subscription_id") - subscription Subscription @relation(fields: [subscriptionId], references: [id], onDelete: Cascade) - userId String @map("user_id") - user User @relation(fields: [userId], references: [id]) - - invoiceNumber String @unique @map("invoice_number") - amountCents Int @map("amount_cents") - currency String @default("USD") - - stripeInvoiceId String? @map("stripe_invoice_id") - stripePaymentIntentId String? @map("stripe_payment_intent_id") - - status String - paidAt DateTime? @map("paid_at") - - periodStart DateTime @map("period_start") - periodEnd DateTime @map("period_end") - dueDate DateTime? @map("due_date") - - pdfUrl String? @map("pdf_url") - - createdAt DateTime @default(now()) @map("created_at") - updatedAt DateTime @updatedAt @map("updated_at") - - @@map("invoices") -} - -model AuditLog { - id String @id @default(uuid()) - - userId String? @map("user_id") - user User? @relation(fields: [userId], references: [id]) - ipAddress String? @map("ip_address") - userAgent String? @map("user_agent") - - action String - resourceType String? @map("resource_type") - resourceId String? @map("resource_id") - - oldValues Json? @map("old_values") - newValues Json? @map("new_values") - - metadata Json @default("{}") - - createdAt DateTime @default(now()) @map("created_at") - - @@map("audit_logs") -} -``` - ---- - -## Data Retention Policies - -**Analytics Data:** -- Page views: Retained for 24 months -- Search queries: Retained for 12 months -- Aggregated data: Retained indefinitely - -**Audit Logs:** -- Retained for 7 years (compliance) -- Partitioned monthly for performance - -**Soft Deletes:** -- User accounts: Permanently deleted after 30 days -- Sites: Permanently deleted after 30 days -- Backups retained for 90 days post-deletion - -**GDPR Compliance:** -- User data export API -- Complete data deletion on request -- No PII in analytics (hashed sessions only) - ---- - -## Performance Optimizations - -**Indexes:** -- Primary keys on all tables (UUID) -- Foreign key indexes -- Query-specific composite indexes -- Partial indexes for active records - -**Partitioning:** -- `page_views` partitioned by month -- `audit_logs` partitioned by month -- Automatic partition creation - -**Caching Strategy:** -- Redis cache for frequently accessed data -- Cache site configs (1 hour TTL) -- Cache user permissions (5 minutes TTL) -- Invalidate on write - -**Query Optimization:** -- Use `SELECT` specific columns (no `SELECT *`) -- Batch inserts for analytics -- Prepared statements -- Connection pooling - ---- - -## Security Measures - -**Authentication:** -- Bcrypt for password hashing (12 rounds) -- JWT tokens for session management -- OAuth 2.0 for social login -- MFA support (TOTP) - -**API Security:** -- HMAC-SHA256 for webhook signatures -- Rate limiting per user/IP -- API token rotation -- Scope-based permissions - -**Data Security:** -- Encryption at rest (AES-256) -- Encryption in transit (TLS 1.3) -- Database credentials in secrets manager -- Regular security audits - -**Privacy:** -- No PII in logs -- Hashed session identifiers -- IP address truncation (last octet removed) -- GDPR-compliant data handling - ---- - -## Backup Strategy - -**Automated Backups:** -- Daily full backups -- Hourly incremental backups -- Point-in-time recovery (7 days) -- Geographic replication - -**Disaster Recovery:** -- RPO (Recovery Point Objective): 1 hour -- RTO (Recovery Time Objective): 4 hours -- Failover to replica in different region -- Regular recovery drills - ---- - -## Monitoring & Alerts - -**Database Metrics:** -- Connection pool usage -- Query performance (slow query log) -- Disk space utilization -- Replication lag - -**Application Metrics:** -- API response times -- Error rates -- User activity -- Resource utilization - -**Alerts:** -- Failed deployments -- Payment failures -- Unusual activity patterns -- System degradation - ---- - -This database schema supports all premium features while maintaining strong security, privacy, and performance standards. diff --git a/docs/examples/api-reference/utilities.md b/docs/examples/api-reference/utilities.md index 78af40e..bd15b19 100644 --- a/docs/examples/api-reference/utilities.md +++ b/docs/examples/api-reference/utilities.md @@ -277,38 +277,9 @@ function findNodeByPath( ): NavigationNode | undefined ``` -### detectVersions() - -Detect Git tag versions for documentation versioning. - -```typescript -function detectVersions(baseDir?: string): Version[] -``` - -**Returns:** - -```typescript -interface Version { - tag: string; - label: string; - isCurrent: boolean; -} -``` - -**Example:** - -```typescript -import { detectVersions } from '@/lib/navigation'; - -const versions = detectVersions(); -// Returns array of Git tag versions -// Example: [{ tag: 'v1.0.0', label: 'v1.0.0', isCurrent: true }] -// Falls back to [{ tag: 'main', label: 'Latest', isCurrent: true }] if no tags -``` - ### generateNavigation() -Complete navigation generation (discovers documents, builds tree, detects versions). +Complete navigation generation (discovers documents, builds tree structure). ```typescript function generateNavigation( @@ -325,7 +296,6 @@ import { generateNavigation } from '@/lib/navigation'; const nav = generateNavigation('./docs/examples'); console.log(nav.roots); // Root navigation nodes console.log(nav.nodeMap); // All nodes by ID -console.log(nav.versions); // Git tag versions ``` ### flattenNavigation() diff --git a/docs/examples/getting-started/installation.md b/docs/examples/getting-started/installation.md index 3356a81..e4c879b 100644 --- a/docs/examples/getting-started/installation.md +++ b/docs/examples/getting-started/installation.md @@ -46,7 +46,7 @@ EmberDocs works with zero configuration, but you can customize branding and beha cp .env.example .env.local # Edit .env.local to customize your site -# See user-docs/Setup.md for all available options +# See dev-docs/Setup.md for all available options ``` **Note:** If you skip this step, EmberDocs will use sensible defaults. You can always add `.env.local` later. diff --git a/docs/examples/getting-started/introduction.md b/docs/examples/getting-started/introduction.md index 6ffa1ee..7644120 100644 --- a/docs/examples/getting-started/introduction.md +++ b/docs/examples/getting-started/introduction.md @@ -19,7 +19,7 @@ EmberDocs is a documentation framework that combines the best of modern web deve - **Fast performance** - Static generation for near-instant page loads - **Great DX** - Simple Markdown syntax with type-safe components - **Search-first** - Full-text search that feels like magic -- **Flexible versioning** - Support for multiple documentation versions +- **Auto-generated navigation** - Sidebar automatically built from your file structure ## Core Concepts @@ -51,7 +51,7 @@ The search index is built at compile time and served as a static JSON file. This - Focus on content, not infrastructure - Simple Markdown syntax -- Built-in versioning support +- Automatic table of contents generation ### For Developers diff --git a/docs/examples/getting-started/quick-start.md b/docs/examples/getting-started/quick-start.md index ecb22a1..7ebaf3a 100644 --- a/docs/examples/getting-started/quick-start.md +++ b/docs/examples/getting-started/quick-start.md @@ -205,7 +205,8 @@ function greet(name: string): string { |---------|--------|-------| | Search | ✅ | FlexSearch powered | | Dark Mode | ✅ | Auto-detects preference | -| Versioning | 🚧 | Coming soon | +| Syntax Highlighting | ✅ | Supports 20+ languages | +| Table of Contents | ✅ | Auto-generated from headings | ### Blockquotes diff --git a/docs/examples/guides/advanced-features.md b/docs/examples/guides/advanced-features.md index 333c087..dd4b2d5 100644 --- a/docs/examples/guides/advanced-features.md +++ b/docs/examples/guides/advanced-features.md @@ -107,38 +107,39 @@ const index = await buildSearchIndex('./docs', { }); ``` -## Versioning Your Documentation +## Custom Sidebar Ordering -EmberDocs supports multiple documentation versions using Git tags: +Control the order of items in your sidebar using the `order` field in frontmatter: -```bash -# Tag a version -git tag v1.0.0 - -# Create a new version -git tag v2.0.0 +```markdown +--- +title: "Getting Started" +slug: "getting-started" +order: 1 +--- -# Switch between versions -git checkout v1.0.0 +# Getting Started ``` -Your build process automatically detects and displays versions. +Items with `order` values are sorted numerically (lower numbers appear first), and items without `order` are sorted alphabetically after ordered items. -### Version Configuration +### Example Ordering -```typescript -// next.config.js -export default { - async redirects() { - return [ - { - source: '/docs/:path*', - destination: '/docs/v2.0.0/:path*', - permanent: false, - }, - ]; - }, -}; +```markdown +--- +title: "Installation" +order: 1 +--- + +--- +title: "Configuration" +order: 2 +--- + +--- +title: "Advanced Topics" +# No order field - will appear after ordered items, alphabetically +--- ``` ## Dark Mode Implementation @@ -352,7 +353,7 @@ Optimize documentation for search engines: ```typescript export const metadata: Metadata = { title: 'EmberDocs - Modern Documentation Framework', - description: 'Build beautiful documentation with Git versioning and instant search', + description: 'Build beautiful documentation with instant search and auto-generated navigation', keywords: ['documentation', 'next.js', 'typescript'], }; ``` diff --git a/docs/examples/index.md b/docs/examples/index.md index 2f9a3a7..3452b1c 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -14,12 +14,12 @@ EmberDocs is a modern documentation framework built with Next.js and TypeScript. ## Key Features -- **Git-native versioning** - Manage multiple documentation versions directly from Git tags - **Instant full-text search** - FlexSearch-powered search that works without a backend - **Dark mode support** - Built-in theme switching with automatic persistence - **Type-safe components** - React components with full TypeScript support - **Markdown-first** - Write documentation in familiar Markdown format - **Zero configuration** - Works out of the box with sensible defaults +- **Auto-generated navigation** - Sidebar automatically built from your file structure ## Quick Navigation diff --git a/dev-docs/ACCESSIBILITY-AUDIT.md b/framework-docs/ACCESSIBILITY-AUDIT.md similarity index 100% rename from dev-docs/ACCESSIBILITY-AUDIT.md rename to framework-docs/ACCESSIBILITY-AUDIT.md diff --git a/dev-docs/EMBERDOCS-LICENSING.md b/framework-docs/EMBERDOCS-LICENSING.md similarity index 100% rename from dev-docs/EMBERDOCS-LICENSING.md rename to framework-docs/EMBERDOCS-LICENSING.md diff --git a/dev-docs/PROJECT-OVERVIEW.md b/framework-docs/PROJECT-OVERVIEW.md similarity index 89% rename from dev-docs/PROJECT-OVERVIEW.md rename to framework-docs/PROJECT-OVERVIEW.md index df6db41..5e3b21c 100644 --- a/dev-docs/PROJECT-OVERVIEW.md +++ b/framework-docs/PROJECT-OVERVIEW.md @@ -22,8 +22,6 @@ emberdocs-complete/ ├── dev-docs/ # Developer documentation │ ├── specs/ # Technical specifications │ │ ├── EMBERDOCS-TECHNICAL-SPEC.md -│ │ ├── EMBERDOCS-DATABASE-SCHEMA.md -│ │ ├── EMBERDOCS-API-SPEC.md │ │ └── EMBERDOCS-ROADMAP.md │ ├── guides/ # Development guides │ │ ├── ARCHITECTURE-DECISIONS.md @@ -72,9 +70,7 @@ Start with the technical spec to understand what you're building. ### 2. Review Technical Architecture Read in this order: -1. `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` - Complete technical overview -2. `dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md` - Data models and storage -3. `dev-docs/specs/EMBERDOCS-API-SPEC.md` - API endpoints and contracts +1. `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` - Complete technical overview ### 3. Understand the Design 1. `brand/EMBERDOCS-STYLE-GUIDE.md` - Colors, typography, components @@ -82,8 +78,8 @@ Read in this order: 3. Open the HTML mockups in your browser to see the UI ### 4. Plan Development -1. `dev-docs/specs/EMBERDOCS-ROADMAP.md` - 16-week development timeline -2. `dev-docs/EMBERDOCS-LICENSING.md` - Licensing model details +1. `framework-docs/specs/EMBERDOCS-ROADMAP.md` - 16-week development timeline +2. `framework-docs/EMBERDOCS-LICENSING.md` - Licensing model details ### 5. Start Building Use the mockups and technical specs to begin implementation. @@ -103,20 +99,6 @@ Use the mockups and technical specs to begin implementation. - CLI tool design - Performance targets (<50ms search, <1s builds) -**specs/EMBERDOCS-DATABASE-SCHEMA.md** (26KB) -- PostgreSQL schema with Prisma ORM -- Multi-tenancy support -- Privacy-first analytics -- Complete table definitions -- Indexes and relationships - -**specs/EMBERDOCS-API-SPEC.md** (17KB) -- REST and GraphQL endpoints -- Authentication (API keys, JWT) -- Content management APIs -- Search API integration -- Webhook system - **specs/EMBERDOCS-ROADMAP.md** (18KB) - 16-week development timeline - Phase 1: Core Framework (Weeks 1-4) @@ -289,9 +271,9 @@ Use the mockups and technical specs to begin implementation. ## 🎯 Next Steps -1. Read `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` +1. Read `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` 2. Browse UI mockups in `mockups/ui/` -3. Review `dev-docs/specs/EMBERDOCS-ROADMAP.md` +3. Review `framework-docs/specs/EMBERDOCS-ROADMAP.md` 4. Start building! --- diff --git a/framework-docs/README.md b/framework-docs/README.md new file mode 100644 index 0000000..f1b8d20 --- /dev/null +++ b/framework-docs/README.md @@ -0,0 +1,49 @@ +# Framework Development Documentation + +This folder contains documentation for **developing the EmberDocs framework itself**, not for using EmberDocs. + +**For users installing and using EmberDocs**, see: +- [`../dev-docs/Setup.md`](../dev-docs/Setup.md) - Installation guide +- [`../dev-docs/Deployment.md`](../dev-docs/Deployment.md) - Deployment guide +- [`../dev-docs/Quick-Reference.md`](../dev-docs/Quick-Reference.md) - User quick reference + +--- + +## Contents + +### Technical Specifications (`specs/`) +- **EMBERDOCS-TECHNICAL-SPEC.md** - Complete technical overview, architecture, and system design +- **EMBERDOCS-ROADMAP.md** - 16-week development timeline and phased plan + +### Development Guides (`guides/`) +- **ARCHITECTURE-DECISIONS.md** - Architecture Decision Log (ADL) - "Why" behind major technical choices +- **DEVELOPMENT-STANDARDS.md** - Universal development standards (code style, testing, Git workflow) +- **DEV-SETUP-VERIFICATION.md** - Local environment setup checklist and verification steps +- **FEATURE-DEPENDENCIES.md** - Dependency graphs, critical path analysis, risk matrix + +### Planning Documents (`planning/`) +- **mvp_phase01of02.md** - Phase 01 detailed deliverables (D1.1-D1.9) +- **mvp_phase02of02.md** - Phase 02 detailed deliverables (D2.1-D2.9) +- **cli_tool_implementation.md** - CLI tool design and implementation plan +- **deferred_frontmatter_ui_editor.md** - Deferred feature documentation + +### Progress Logs (`progress/`) +Daily work logs following format: `YYYY_MM_DD.md` or `YYYY_MM_DD_description.md` + +### Other Framework Docs +- **PROJECT-OVERVIEW.md** - Complete package overview and framework architecture +- **USER-STORIES.md** - User personas and stories for framework planning +- **EMBERDOCS-LICENSING.md** - Licensing model and terms +- **ACCESSIBILITY-AUDIT.md** - Accessibility audit results and compliance + +--- + +## For Contributors + +If you're contributing to the EmberDocs framework: + +1. Read [`../AGENTS.md`](../AGENTS.md) for contributing guidelines +2. Review [`guides/ARCHITECTURE-DECISIONS.md`](guides/ARCHITECTURE-DECISIONS.md) for locked decisions +3. Check [`guides/DEVELOPMENT-STANDARDS.md`](guides/DEVELOPMENT-STANDARDS.md) for coding standards +4. Follow [`guides/DEV-SETUP-VERIFICATION.md`](guides/DEV-SETUP-VERIFICATION.md) for setup + diff --git a/dev-docs/USER-STORIES.md b/framework-docs/USER-STORIES.md similarity index 89% rename from dev-docs/USER-STORIES.md rename to framework-docs/USER-STORIES.md index 22a83e9..97e9571 100644 --- a/dev-docs/USER-STORIES.md +++ b/framework-docs/USER-STORIES.md @@ -20,8 +20,8 @@ Primary personas and outcome-driven stories for EmberDocs. Use these to guide pl - Milestone: MVP Phase 02 — git tag parser, versioned routes, selector UI, fallback logic. - Contributor preview - - Acceptance: PR automatically builds preview with MDX changes; links posted to PR; build fails on lint/test errors. - - Milestone: MVP Phase 02 — CI preview pipeline, lint/test gates, MDX render checks. + - Acceptance: PR automatically builds preview with markdown changes; links posted to PR; build fails on lint/test errors. + - Milestone: MVP Phase 02 — CI preview pipeline, lint/test gates, markdown render checks. - Reader search - Acceptance: ⌘K/ctrl+k opens modal; search hits titles/headings/code; p50 <50ms on sample corpus; keyboard navigation works. @@ -40,7 +40,7 @@ Primary personas and outcome-driven stories for EmberDocs. Use these to guide pl - Milestone: MVP Phase 02 — env guards, safe fallbacks, docs in `dev-docs/`. - Developer visibility - - Acceptance: each workday has `dev-docs/progress/YYYY_MM_DD_progress.md`; phase plans live in `dev-docs/planning/`; links referenced in PRs. + - Acceptance: each workday has `framework-docs/progress/YYYY_MM_DD_progress.md`; phase plans live in `framework-docs/planning/`; links referenced in PRs. - Milestone: Ongoing — process enforced from first sprint; tracked in PR template. - User deployment guides diff --git a/dev-docs/guides/ARCHITECTURE-DECISIONS.md b/framework-docs/guides/ARCHITECTURE-DECISIONS.md similarity index 93% rename from dev-docs/guides/ARCHITECTURE-DECISIONS.md rename to framework-docs/guides/ARCHITECTURE-DECISIONS.md index 9de3263..3ef4a85 100644 --- a/dev-docs/guides/ARCHITECTURE-DECISIONS.md +++ b/framework-docs/guides/ARCHITECTURE-DECISIONS.md @@ -32,7 +32,7 @@ Use Next.js 16 App Router (not Pages Router) with TypeScript 5 in strict mode (` - ⚠️ Steeper learning curve for contributors unfamiliar with modern React patterns - ⚠️ Requires discipline to prevent over-component-ization -**Related Docs:** `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md`, `tsconfig.json` +**Related Docs:** `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md`, `tsconfig.json` --- @@ -91,7 +91,7 @@ Implement search using FlexSearch (JavaScript library). Pre-generate search inde - ⚠️ Updating search index requires full rebuild/deploy (not real-time) - ⚠️ Client-side search less suitable for massive doc repositories -**Related Docs:** `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md#search-indexing`, `dev-docs/planning/mvp_phase01of02.md` +**Related Docs:** `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md#search-indexing`, `framework-docs/planning/mvp_phase01of02.md` --- @@ -119,7 +119,7 @@ Use PostgreSQL as the primary database (optional; can run without it). Prisma OR - ⚠️ Deployment requires database setup (adds complexity for "free tier" users) - ⚠️ Type sync between Prisma and business logic requires discipline -**Related Docs:** `dev-docs/specs/EMBERDOCS-DATABASE-SCHEMA.md`, `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md#database` +**Related Docs:** `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md#database` --- @@ -147,7 +147,7 @@ Versions are defined by Git tags (e.g., `v1.0`, `v2.0`) or branch names in the d - ⚠️ Requires Git repo for docs; not suitable for non-code content - ⚠️ End users (non-developers) may find version switching less intuitive -**Related Docs:** `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md#versioning`, `dev-docs/planning/mvp_phase01of02.md` +**Related Docs:** `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md#versioning`, `framework-docs/planning/mvp_phase01of02.md` --- @@ -179,7 +179,7 @@ Full feature set (versioning, team accounts, analytics) deferred to Beta/v1.0. - ⚠️ Risk of scope creep if phases not strictly enforced - ⚠️ Deferred features (versioning, analytics) may feel incomplete -**Related Docs:** `dev-docs/planning/mvp_phase01of02.md`, `dev-docs/planning/mvp_phase02of02.md`, `dev-docs/specs/EMBERDOCS-ROADMAP.md` +**Related Docs:** `framework-docs/planning/mvp_phase01of02.md`, `framework-docs/planning/mvp_phase02of02.md`, `framework-docs/specs/EMBERDOCS-ROADMAP.md` --- @@ -221,7 +221,7 @@ Set target at **<100ms per query on 1000 docs** with index JSON <500KB. - ✅ Can still optimize further if needed - ⚠️ Some users may see 80–100ms on very large doc sites (acceptable trade-off) -**Related Docs:** `dev-docs/planning/mvp_phase01of02.md` (D1.3), `dev-docs/guides/FEATURE-DEPENDENCIES.md` +**Related Docs:** `framework-docs/planning/mvp_phase01of02.md` (D1.3), `framework-docs/guides/FEATURE-DEPENDENCIES.md` --- @@ -258,7 +258,7 @@ Keep Git-tag approach for MVP. Fallback gracefully if Git unavailable: **Deferred to v1.0:** Dynamic version management (add/remove versions without rebuild), database-backed versioning. -**Related Docs:** `dev-docs/planning/mvp_phase02of02.md` (D2.5), `dev-docs/guides/FEATURE-DEPENDENCIES.md` +**Related Docs:** `framework-docs/planning/mvp_phase02of02.md` (D2.5), `framework-docs/guides/FEATURE-DEPENDENCIES.md` --- @@ -303,7 +303,7 @@ Use hybrid approach to balance speed and safety: - `src/components/` (React): ≥60% - Tests run in <10s; CI fails if below threshold -**Related Docs:** `dev-docs/planning/mvp_phase01of02.md` (D1.8), `dev-docs/Quick-Reference.md` (testing tips) +**Related Docs:** `framework-docs/planning/mvp_phase01of02.md` (D1.8), `dev-docs/Quick-Reference.md` (testing tips) --- @@ -352,7 +352,7 @@ Implement **WCAG 2.1 Level AA** as MVP target. Phase 02 Week 1 (D2.2) includes 3 **Legal Compliance:** Consult legal counsel if operating in regulated industry. For general SaaS, WCAG 2.1 AA is standard and defensible. -**Related Docs:** `dev-docs/planning/mvp_phase02of02.md` (D2.2), WebAIM guides, WCAG 2.1 spec +**Related Docs:** `framework-docs/planning/mvp_phase02of02.md` (D2.2), WebAIM guides, WCAG 2.1 spec --- @@ -378,7 +378,7 @@ Implement **WCAG 2.1 Level AA** as MVP target. Phase 02 Week 1 (D2.2) includes 3 - ✅ Less risk of license messaging drift across docs and marketing - ⚠️ Requires clear contributor guidance on redistribution restrictions -**Related Docs:** `LICENSE`, `dev-docs/EMBERDOCS-LICENSING.md`, `NOTICES.md` +**Related Docs:** `LICENSE`, `framework-docs/EMBERDOCS-LICENSING.md`, `NOTICES.md` --- diff --git a/dev-docs/guides/DEV-SETUP-VERIFICATION.md b/framework-docs/guides/DEV-SETUP-VERIFICATION.md similarity index 98% rename from dev-docs/guides/DEV-SETUP-VERIFICATION.md rename to framework-docs/guides/DEV-SETUP-VERIFICATION.md index da1a9e1..d7576b0 100644 --- a/dev-docs/guides/DEV-SETUP-VERIFICATION.md +++ b/framework-docs/guides/DEV-SETUP-VERIFICATION.md @@ -411,7 +411,7 @@ Once setup is verified: 1. **Read the docs:** - Start with `dev-docs/Quick-Reference.md` for common commands - - Read `dev-docs/planning/mvp_phase01of02.md` to understand Phase 01 scope + - Read `framework-docs/planning/mvp_phase01of02.md` to understand Phase 01 scope 2. **Explore the codebase:** - `src/app/page.tsx` — homepage (great starting point) @@ -429,7 +429,7 @@ Once setup is verified: - Run `npm run check` to verify all tests pass 5. **Create a progress log:** - - Create `dev-docs/progress/YYYY_MM_DD_progress.md` + - Create `framework-docs/progress/YYYY_MM_DD_progress.md` - Document what you did and what you'll do next --- diff --git a/dev-docs/guides/DEVELOPMENT-STANDARDS.md b/framework-docs/guides/DEVELOPMENT-STANDARDS.md similarity index 87% rename from dev-docs/guides/DEVELOPMENT-STANDARDS.md rename to framework-docs/guides/DEVELOPMENT-STANDARDS.md index 2a4cd4c..4c48f26 100644 --- a/dev-docs/guides/DEVELOPMENT-STANDARDS.md +++ b/framework-docs/guides/DEVELOPMENT-STANDARDS.md @@ -39,14 +39,14 @@ This document defines the universal development standards for EmberDocs. When making meaningful changes: - Update `CHANGELOG.md` under `[Unreleased]`. -- Create a progress log in `dev-docs/progress/YYYY_MM_DD.md`. -- If you make a major architecture decision, update `dev-docs/guides/ARCHITECTURE-DECISIONS.md`. +- Create a progress log in `framework-docs/progress/YYYY_MM_DD.md`. +- If you make a major architecture decision, update `framework-docs/guides/ARCHITECTURE-DECISIONS.md`. Useful references: - `dev-docs/Quick-Reference.md` -- `dev-docs/guides/DEV-SETUP-VERIFICATION.md` -- `dev-docs/guides/ARCHITECTURE-DECISIONS.md` +- `framework-docs/guides/DEV-SETUP-VERIFICATION.md` +- `framework-docs/guides/ARCHITECTURE-DECISIONS.md` ## Security and configuration diff --git a/dev-docs/guides/FEATURE-DEPENDENCIES.md b/framework-docs/guides/FEATURE-DEPENDENCIES.md similarity index 96% rename from dev-docs/guides/FEATURE-DEPENDENCIES.md rename to framework-docs/guides/FEATURE-DEPENDENCIES.md index bb16971..3ab4436 100644 --- a/dev-docs/guides/FEATURE-DEPENDENCIES.md +++ b/framework-docs/guides/FEATURE-DEPENDENCIES.md @@ -14,7 +14,7 @@ This document maps dependencies between features to guide implementation sequenc Week 1: Foundation ├─ D1.1: Content Pipeline - │ ├─ Markdown/MDX parsing + │ ├─ Markdown parsing │ ├─ Frontmatter extraction │ └─ TOC generation ├─ Base Layout (Layout.tsx) @@ -294,8 +294,8 @@ When planning a new feature, ask: ## Related Documents -- **Phase 01 Plan:** `dev-docs/planning/mvp_phase01of02.md` (detailed deliverables D1.1–D1.9) -- **Phase 02 Plan:** `dev-docs/planning/mvp_phase02of02.md` (detailed deliverables D2.1–D2.9) -- **Architecture Decisions:** `dev-docs/guides/ARCHITECTURE-DECISIONS.md` (why we chose these features) +- **Phase 01 Plan:** `framework-docs/planning/mvp_phase01of02.md` (detailed deliverables D1.1–D1.9) +- **Phase 02 Plan:** `framework-docs/planning/mvp_phase02of02.md` (detailed deliverables D2.1–D2.9) +- **Architecture Decisions:** `framework-docs/guides/ARCHITECTURE-DECISIONS.md` (why we chose these features) - **Quick Reference:** `dev-docs/Quick-Reference.md` (developer cheat sheet) diff --git a/dev-docs/planning/cli_tool_implementation.md b/framework-docs/planning/cli_tool_implementation.md similarity index 100% rename from dev-docs/planning/cli_tool_implementation.md rename to framework-docs/planning/cli_tool_implementation.md diff --git a/dev-docs/planning/deferred_frontmatter_ui_editor.md b/framework-docs/planning/deferred_frontmatter_ui_editor.md similarity index 100% rename from dev-docs/planning/deferred_frontmatter_ui_editor.md rename to framework-docs/planning/deferred_frontmatter_ui_editor.md diff --git a/dev-docs/planning/mvp_phase01of02.md b/framework-docs/planning/mvp_phase01of02.md similarity index 95% rename from dev-docs/planning/mvp_phase01of02.md rename to framework-docs/planning/mvp_phase01of02.md index 1430e27..61e14db 100644 --- a/dev-docs/planning/mvp_phase01of02.md +++ b/framework-docs/planning/mvp_phase01of02.md @@ -9,7 +9,7 @@ ## Scope ### Content Ingestion & Processing -- Markdown and MDX file parsing with YAML frontmatter support +- Markdown file parsing with YAML frontmatter support - Automatic Table of Contents (TOC) generation from heading hierarchy - Syntax highlighting for code blocks (Shiki or Prism.js) - Slug generation and URL-safe filenames from doc paths @@ -153,7 +153,7 @@ ### D1.9: Documentation & Contributor Guides - **Deliverable:** - Update `AGENTS.md` / `claude.md` with Phase 01 completion notes - - Daily progress log: `dev-docs/progress/YYYY_MM_DD_progress.md` + - Daily progress log: `framework-docs/progress/YYYY_MM_DD_progress.md` - README section: "Getting Started for Contributors" - API reference for content, search, and nav modules in `docs/` - **Acceptance Criteria:** @@ -173,7 +173,7 @@ - [ ] Theme toggle component and dark/light CSS variables - [ ] Sample docs created (`docs/examples/`) - [ ] `npm run dev` works; homepage renders -- [ ] First daily progress log: `dev-docs/progress/YYYY_MM_DD_progress.md` +- [ ] First daily progress log: `framework-docs/progress/YYYY_MM_DD_progress.md` **Definition of Done:** - Content parsing tests pass (≥ 70% coverage) @@ -282,7 +282,7 @@ ## Related Documents -- **Technical Spec:** `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (architecture, data structures) -- **Architecture Decisions:** `dev-docs/guides/ARCHITECTURE-DECISIONS.md` (ADL-001, ADL-003, ADL-004, ADL-005) -- **Roadmap:** `dev-docs/specs/EMBERDOCS-ROADMAP.md` (overview of Beta/v1.0 features) -- **Phase 02:** `dev-docs/planning/mvp_phase02of02.md` (stabilization) +- **Technical Spec:** `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (architecture, data structures) +- **Architecture Decisions:** `framework-docs/guides/ARCHITECTURE-DECISIONS.md` (ADL-001, ADL-003, ADL-004, ADL-005) +- **Roadmap:** `framework-docs/specs/EMBERDOCS-ROADMAP.md` (overview of Beta/v1.0 features) +- **Phase 02:** `framework-docs/planning/mvp_phase02of02.md` (stabilization) diff --git a/dev-docs/planning/mvp_phase02of02.md b/framework-docs/planning/mvp_phase02of02.md similarity index 94% rename from dev-docs/planning/mvp_phase02of02.md rename to framework-docs/planning/mvp_phase02of02.md index d4fb1ca..fe778eb 100644 --- a/dev-docs/planning/mvp_phase02of02.md +++ b/framework-docs/planning/mvp_phase02of02.md @@ -26,9 +26,8 @@ ### Documentation & User Guides - **Developer Docs:** Architecture deep dives, contribution guide - **User Docs:** Setup guide, deployment guide, configuration reference, troubleshooting -- **Daily Progress Logs:** Continue logging in `dev-docs/progress/` +- **Daily Progress Logs:** Continue logging in `framework-docs/progress/` - **Changelog:** Alpha/Beta release notes with breaking changes, new features, fixes -- **API Reference:** REST/GraphQL endpoints (from `emberdocs-api-spec.md`) ### Deployment & CI/CD - GitHub Actions matrix: lint + typecheck + test + build on multiple Node versions @@ -96,7 +95,7 @@ ### D2.6: Documentation Expansion (Docs in `dev-docs/`) - **Developer Documentation:** - - `dev-docs/guides/ARCHITECTURE-DECISIONS.md` — data flow, module responsibilities, extension points + - `framework-docs/guides/ARCHITECTURE-DECISIONS.md` — data flow, module responsibilities, extension points - `AGENTS.md` — how to contribute, code style, PR process - API reference for `src/lib/` modules (auto-generated from JSDoc or manually curated) @@ -282,8 +281,7 @@ After Phase 02 exit criteria met: ## Related Documents -- **Phase 01:** `dev-docs/planning/mvp_phase01of02.md` (core engine) -- **Technical Spec:** `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (architecture) -- **Architecture Decisions:** `dev-docs/guides/ARCHITECTURE-DECISIONS.md` (ADL-006, ADL-007) -- **Roadmap:** `dev-docs/specs/EMBERDOCS-ROADMAP.md` (Beta/v1.0 overview) -- **API Spec:** `dev-docs/specs/EMBERDOCS-API-SPEC.md` (REST/GraphQL endpoints, for future documentation) +- **Phase 01:** `framework-docs/planning/mvp_phase01of02.md` (core engine) +- **Technical Spec:** `framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (architecture) +- **Architecture Decisions:** `framework-docs/guides/ARCHITECTURE-DECISIONS.md` (ADL-006, ADL-007) +- **Roadmap:** `framework-docs/specs/EMBERDOCS-ROADMAP.md` (Beta/v1.0 overview) diff --git a/dev-docs/progress/2025_12_23_d1.1_completion.md b/framework-docs/progress/2025_12_23_d1.1_completion.md similarity index 99% rename from dev-docs/progress/2025_12_23_d1.1_completion.md rename to framework-docs/progress/2025_12_23_d1.1_completion.md index 71f37e2..9ae7923 100644 --- a/dev-docs/progress/2025_12_23_d1.1_completion.md +++ b/framework-docs/progress/2025_12_23_d1.1_completion.md @@ -194,7 +194,7 @@ expect(result.frontmatter.version).toBe(1); ## D1.1 Acceptance Criteria — Verified ✅ -From `dev-docs/planning/mvp_phase01of02.md`: +From `framework-docs/planning/mvp_phase01of02.md`: | Criterion | Result | Evidence | |-----------|--------|----------| diff --git a/dev-docs/progress/2025_12_23_d1.2_completion.md b/framework-docs/progress/2025_12_23_d1.2_completion.md similarity index 99% rename from dev-docs/progress/2025_12_23_d1.2_completion.md rename to framework-docs/progress/2025_12_23_d1.2_completion.md index 430e254..b213656 100644 --- a/dev-docs/progress/2025_12_23_d1.2_completion.md +++ b/framework-docs/progress/2025_12_23_d1.2_completion.md @@ -165,7 +165,7 @@ content.ts 88.4 84 71.42 88.05 ## D1.2 Acceptance Criteria — Verified ✅ -From `dev-docs/planning/mvp_phase01of02.md`: +From `framework-docs/planning/mvp_phase01of02.md`: | Criterion | Result | Evidence | |-----------|--------|----------| diff --git a/dev-docs/progress/2025_12_23_d1.3_completion.md b/framework-docs/progress/2025_12_23_d1.3_completion.md similarity index 99% rename from dev-docs/progress/2025_12_23_d1.3_completion.md rename to framework-docs/progress/2025_12_23_d1.3_completion.md index b280f85..1f3c141 100644 --- a/dev-docs/progress/2025_12_23_d1.3_completion.md +++ b/framework-docs/progress/2025_12_23_d1.3_completion.md @@ -172,7 +172,7 @@ These are defensive paths in production code; the core search functionality func ## D1.3 Acceptance Criteria — Verified ✅ -From `dev-docs/planning/mvp_phase01of02.md`: +From `framework-docs/planning/mvp_phase01of02.md`: | Criterion | Result | Evidence | |-----------|--------|----------| diff --git a/dev-docs/progress/2025_12_23_d1456_completion.md b/framework-docs/progress/2025_12_23_d1456_completion.md similarity index 100% rename from dev-docs/progress/2025_12_23_d1456_completion.md rename to framework-docs/progress/2025_12_23_d1456_completion.md diff --git a/dev-docs/progress/2025_12_23_phase02_quick_wins.md b/framework-docs/progress/2025_12_23_phase02_quick_wins.md similarity index 100% rename from dev-docs/progress/2025_12_23_phase02_quick_wins.md rename to framework-docs/progress/2025_12_23_phase02_quick_wins.md diff --git a/dev-docs/progress/2025_12_23_progress.md b/framework-docs/progress/2025_12_23_progress.md similarity index 88% rename from dev-docs/progress/2025_12_23_progress.md rename to framework-docs/progress/2025_12_23_progress.md index 903e36b..72d38b8 100644 --- a/dev-docs/progress/2025_12_23_progress.md +++ b/framework-docs/progress/2025_12_23_progress.md @@ -43,17 +43,17 @@ |------|-------|---------| | `DEVELOPMENT-STANDARDS.md` | ~800 | Universal standards template (reusable across projects) | | `dev-docs/Quick-Reference.md` | ~280 | Developer cheat sheet (common commands, patterns, FAQ) | -| `dev-docs/guides/FEATURE-DEPENDENCIES.md` | ~380 | Dependency graphs (critical path, risk matrix) | -| `dev-docs/guides/DEV-SETUP-VERIFICATION.md` | ~420 | Local environment setup checklist (node_modules → npm run check) | +| `framework-docs/guides/FEATURE-DEPENDENCIES.md` | ~380 | Dependency graphs (critical path, risk matrix) | +| `framework-docs/guides/DEV-SETUP-VERIFICATION.md` | ~420 | Local environment setup checklist (node_modules → npm run check) | | `CHANGELOG.md` | ~300 | Release notes template (Keep a Changelog + SemVer format) | ### 3. Files Enhanced (Existing) | File | Before | After | Changes | |------|--------|-------|---------| -| `dev-docs/guides/ARCHITECTURE-DECISIONS.md` | ADL-001–007 | Updated | Added ADL-009 through ADL-012 with full context, alternatives, consequences | -| `dev-docs/planning/mvp_phase01of02.md` | 27 lines | 289 lines | Added 9 deliverables (D1.1–D1.9) + weekly milestones + KPIs + exit criteria | -| `dev-docs/planning/mvp_phase02of02.md` | 27 lines | 321 lines | Added 9 deliverables (D2.1–D2.9) + prerequisites + risk assessment | +| `framework-docs/guides/ARCHITECTURE-DECISIONS.md` | ADL-001–007 | Updated | Added ADL-009 through ADL-012 with full context, alternatives, consequences | +| `framework-docs/planning/mvp_phase01of02.md` | 27 lines | 289 lines | Added 9 deliverables (D1.1–D1.9) + weekly milestones + KPIs + exit criteria | +| `framework-docs/planning/mvp_phase02of02.md` | 27 lines | 321 lines | Added 9 deliverables (D2.1–D2.9) + prerequisites + risk assessment | | `.cursorrules` | 46 lines | 117 lines | Added "Universal Standards" section, project-specific rules, sync instructions | | `claude.md` | 46 lines | 275 lines | Added detailed guidelines, TypeScript examples, doc requirements, locked decisions | | `AGENTS.md` | 46 lines | 463 lines | Added 7-step contributing workflow, code review checklist, sync instructions | @@ -104,7 +104,7 @@ export interface ContentData { ``` **Task 2: Implement D1.1 Content Pipeline** (`src/lib/content.ts`) -- Parse Markdown/MDX files +- Parse Markdown files - Extract YAML frontmatter - Generate table of contents - Handle edge cases (missing frontmatter, malformed YAML) @@ -143,7 +143,7 @@ All user decisions locked (Message 3 of conversation): **Reference Documentation:** - `dev-docs/Quick-Reference.md` — Common commands and patterns -- `dev-docs/planning/mvp_phase01of02.md` — D1.1 detailed acceptance criteria (D1.1.1–D1.1.5) +- `framework-docs/planning/mvp_phase01of02.md` — D1.1 detailed acceptance criteria (D1.1.1–D1.1.5) - `DEVELOPMENT-STANDARDS.md` — Universal standards (naming, testing, TypeScript) - `claude.md` — TypeScript examples and guidelines diff --git a/dev-docs/progress/2025_12_24.md b/framework-docs/progress/2025_12_24.md similarity index 100% rename from dev-docs/progress/2025_12_24.md rename to framework-docs/progress/2025_12_24.md diff --git a/dev-docs/progress/2025_12_24_ux_improvements.md b/framework-docs/progress/2025_12_24_ux_improvements.md similarity index 99% rename from dev-docs/progress/2025_12_24_ux_improvements.md rename to framework-docs/progress/2025_12_24_ux_improvements.md index 235ad0c..8978f4c 100644 --- a/dev-docs/progress/2025_12_24_ux_improvements.md +++ b/framework-docs/progress/2025_12_24_ux_improvements.md @@ -552,8 +552,8 @@ b95ba68 - feat: add mobile navigation, syntax highlighting, and landing page imp ## References - UX Review: `~/.claude/plans/humble-wondering-metcalfe.md` -- Architecture Decisions: `dev-docs/guides/ARCHITECTURE-DECISIONS.md` -- Phase 01 Plan: `dev-docs/planning/mvp_phase01of02.md` +- Architecture Decisions: `framework-docs/guides/ARCHITECTURE-DECISIONS.md` +- Phase 01 Plan: `framework-docs/planning/mvp_phase01of02.md` - Style Guide: `brand/EMBERDOCS-STYLE-GUIDE.md` --- diff --git a/dev-docs/progress/2025_12_27.md b/framework-docs/progress/2025_12_27.md similarity index 91% rename from dev-docs/progress/2025_12_27.md rename to framework-docs/progress/2025_12_27.md index 198621c..26b3de5 100644 --- a/dev-docs/progress/2025_12_27.md +++ b/framework-docs/progress/2025_12_27.md @@ -16,7 +16,7 @@ ### Documentation updates - Updated component API docs for `SearchPalette` to show the correct props and usage pattern. -- Updated developer quick reference to use the standard `dev-docs/progress/YYYY_MM_DD.md` filename format. +- Updated developer quick reference to use the standard `framework-docs/progress/YYYY_MM_DD.md` filename format. ### Changelog updates - Updated `[Unreleased]` to capture the search palette behavior and UI fixes, and removal of the old context helper. diff --git a/dev-docs/specs/EMBERDOCS-ROADMAP.md b/framework-docs/specs/EMBERDOCS-ROADMAP.md similarity index 100% rename from dev-docs/specs/EMBERDOCS-ROADMAP.md rename to framework-docs/specs/EMBERDOCS-ROADMAP.md diff --git a/dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md b/framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md similarity index 99% rename from dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md rename to framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md index ed2ad90..8b50c41 100644 --- a/dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md +++ b/framework-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md @@ -837,7 +837,7 @@ export function CodeBlock({ ## CLI Tool -**Status:** Planned for Phase 02 / Future Version (see `dev-docs/planning/cli_tool_implementation.md`) +**Status:** Planned for Phase 02 / Future Version (see `framework-docs/planning/cli_tool_implementation.md`) The CLI tool is not yet implemented. Users currently need to clone the repository and set up manually. The CLI functionality described below is planned for future releases. @@ -1127,4 +1127,4 @@ npx emberdocs migrate --from gitbook --- -This specification provides the foundation for v1.0 development. Additional detailed specifications for database schema, brand guidelines, and development roadmap follow in separate documents. +This specification provides the foundation for v1.0 development. Additional detailed specifications for brand guidelines and development roadmap follow in separate documents. diff --git a/src/app/page.tsx b/src/app/page.tsx index 807cee4..a1950dd 100644 --- a/src/app/page.tsx +++ b/src/app/page.tsx @@ -51,12 +51,6 @@ export default function HomePage() {
The one that starts with a "D"
The one that starts with a "G"
-
-
Setup time
-
Typically 2 minutes
-
15 minutes
-
5 minutes
-
Zero config
✓
diff --git a/src/components/landing/Features.tsx b/src/components/landing/Features.tsx index 59286ff..e4a3d7e 100644 --- a/src/components/landing/Features.tsx +++ b/src/components/landing/Features.tsx @@ -39,9 +39,9 @@ export function Features({ theme }: FeaturesProps): JSX.Element {
-
🔄
-

Git Versioning

-

Version detection from Git tags (routing planned for Phase 02). No manual configuration needed.

+
📝
+

Markdown First

+

Write in standard markdown with YAML frontmatter. No special syntax or build steps required.

@@ -83,8 +83,8 @@ export function Features({ theme }: FeaturesProps): JSX.Element {
-

Git Native

-

Git-native versioning (detection implemented, routing planned for Phase 02). Version tags become versioned docs.

+

Syntax Highlighting

+

Beautiful code blocks with syntax highlighting for 20+ languages. Copy button included.

diff --git a/src/lib/content.ts b/src/lib/content.ts index 17b2342..b64b9e1 100644 --- a/src/lib/content.ts +++ b/src/lib/content.ts @@ -1,6 +1,6 @@ /** * Content Pipeline Module (D1.1) - * Parses markdown/MDX files with YAML frontmatter and generates table of contents + * Parses markdown files with YAML frontmatter and generates table of contents */ import yaml from 'js-yaml';