Skip to content

Latest commit

 

History

History
450 lines (344 loc) · 12.7 KB

Quick-Reference.md

File metadata and controls

450 lines (344 loc) · 12.7 KB

EmberDocs Developer Quick Reference

Bookmark this page. This is your command reference for common development tasks.

Setup & Installation

# Clone and install
git clone https://github.com/sturdy-barnacle/emberdocs.git
cd emberdocs
npm install

# First time only: seed environment variables
cp .env.example .env.local

# Start development server
npm run dev

# Open in browser
open http://localhost:3000

Common npm Scripts

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.

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)

// 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');
  });

  it('should validate required frontmatter fields', () => {
    const invalidMarkdown = `---
slug: "missing-title"
---
Body`;

    expect(() => parseMarkdown(invalidMarkdown)).toThrow('title is required');
  });
});

Run tests:

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

// ✅ Good: Tailwind utilities
<div className="flex flex-col gap-4 p-6 bg-slate-900 dark:bg-slate-950 text-white rounded-lg">
  Content
</div>

// ❌ Avoid: Custom CSS or inline styles
<div style={{ display: 'flex', gap: '16px' }}>
  Content
</div>

Using CSS Variables (Theme Colors)

// src/app/globals.css
:root {
  --color-primary: #7f5af0;
  --color-background: #ffffff;
  --color-text: #1a1a1a;
}

[data-theme='dark'] {
  --color-background: #0a0a0a;
  --color-text: #f5f5f5;
}
// In React component
<div className="bg-[var(--color-background)] text-[var(--color-text)]">
  Theme-aware content
</div>

Creating a New Document

1. Create Markdown File

# Save to dev-docs/guides/my-guide.md
mkdir -p dev-docs/guides
touch dev-docs/guides/my-guide.md

2. Add Frontmatter

---
title: "My Guide"
slug: "my-guide"
published: true
date: "2025-12-23"
author: "Your Name"
---

# My Guide

Content here...

3. Test Locally

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

Creating a Progress Log

Each day, create dev-docs/progress/YYYY_MM_DD.md:

# 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

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

Editing Documentation

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

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

Progress (in dev-docs/progress/)

  • Purpose: Daily work logs
  • Files: YYYY_MM_DD_progress.md
  • Update when: End of each work day

Rule: Keep related documents cross-linked. If you change a spec, link the PR from the progress log.

Git Workflow

Branching

# Create feature branch
git checkout -b feature/search-ranking

# Or chore/docs branch
git checkout -b chore/docs-refresh

# Push to remote
git push origin feature/search-ranking

Commit Messages (Imperative, Short)

# ✅ 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"

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)

TypeScript Tips

Typed Function Exports

// ✅ 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 <article>{content}</article>;
}

// ❌ Avoid implicit `any`
export function parseMarkdown(content) { // ← implicit any
  // ...
}

Strict Mode Benefits

  • Enables stricter null/undefined checking
  • Catches more errors at compile time
  • Better IntelliSense in editor

Check tsconfig.json: "strict": true

Debugging

Browser DevTools

// Log to browser console
console.log('Search index size:', indexData.length);
console.time('search-query');
const results = search(query);
console.timeEnd('search-query');

Build-Time Debugging

# Show Next.js build info
npm run build -- --debug

# Check bundle size
npm run build -- --analyze

# Verbose ESLint output
npm run lint -- --debug

Testing Specific File

npm test -- src/lib/search.test.ts
npm test -- --watch src/lib/search.test.ts

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: 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 add a new npm dependency? A: Run npm install <package>, commit package-lock.json, then test locally with npm run check.

Q: Can I run tests for just one component? A: Yes! npm test -- MyComponent.test.ts

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: How do I preview a build locally? A: Run npm run build && npm start (starts production server on 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.

Resources

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

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)