EmberDocs

Modern documentation framework with Git-native versioning, instant search, and developer-focused design.

---

🚀 Quick Start

Get up and running in typically 2 minutes (with Node.js 18+ installed):

# Clone the repository
git clone https://github.com/sturdy-barnacle/emberdocs.git
cd emberdocs

# Install dependencies (~1-2 minutes)
npm install

# Configure (optional - EmberDocs works with defaults)
cp .env.example .env.local

# Start development server
npm run dev

Visit http://localhost:3000 to see your documentation site.

Note: The search index is automatically built during production builds (npm run build). For development, you can manually build it with npm run build:search if needed, but it's not required to get started.

Note: By default, the root route (/) redirects to your documentation index. To show the EmberDocs framework marketing landing page, set EMBERDOCS_SHOW_LANDING=true in .env.local.

Custom Documentation Content Directory

By default, EmberDocs uses docs/examples/ for documentation files. You can customize this by setting EMBERDOCS_CONTENT_DIR in .env.local:

# In .env.local
EMBERDOCS_CONTENT_DIR=docs/content  # Files stored in docs/content/ folder

After changing the directory, rebuild the search index:

npm run build:search

Custom Documentation Base Route

By default, documentation pages are served at /docs/*. You can change this URL prefix by setting EMBERDOCS_BASE_ROUTE in .env.local:

# In .env.local
EMBERDOCS_BASE_ROUTE=/documentation  # URLs: /documentation/getting-started/intro
EMBERDOCS_BASE_ROUTE=/help           # URLs: /help/getting-started/intro

Example: Use different directory and URL:

EMBERDOCS_CONTENT_DIR=content              # Files in content/ folder
EMBERDOCS_BASE_ROUTE=/documentation        # URLs at /documentation/*

---

📖 About EmberDocs

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
• Zero Config - Typically 2-minute setup time (with Node.js 18+ installed)
• Privacy First - No third-party trackers
• Free Forever - Core framework free to self-host
• Theme Options - Choose between dark (default), light, or monochrome theme via EMBERDOCS_THEME

---

🛠 Technology Stack

Layer	Technology
Frontend	Next.js 16+, React 18+, TypeScript 5+
Styling	Tailwind CSS 3+
Search	FlexSearch (client-side)
Deployment	Vercel, Netlify, or self-hosted

---

📂 Project Structure

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

---

📚 Documentation

For Developers

• Technical Specification - Complete technical overview
• Database Schema - Data models and storage
• API Specification - REST and GraphQL endpoints
• Roadmap - Phased development plan
• User Stories - User personas and stories

For Designers

• Style Guide - Complete design system
• Brand Guidelines - Logo usage and brand identity
• UI Mockups - Application screen designs
• Landing Mockups - Marketing page variations

For Contributors

• Development Roadmap - 16-week development timeline
• Licensing - Proprietary core license (source-available)

---

🎯 Key Features

Core Features

• ✅ Markdown & MDX support
• ✅ Git-based versioning
• ✅ Full-text search (<50ms for typical queries)
• ✅ Dark/light themes
• ✅ Mobile responsive
• ✅ 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

---

🔐 License

• Core Framework: Proprietary source-available license (free to use and self-host; redistribution is not permitted)
• Hosted Service: Proprietary (optional premium offering)

See EMBERDOCS-LICENSING.md for details.

---

🤝 Contributing

We welcome your feedback and bug reports! The best way to contribute is by submitting Issues:

• Bug Reports - Found a bug? Open an issue
• Feature Requests - Have an idea? Suggest a feature
• Documentation - Found an error or have a suggestion? Report it
• Questions - Use GitHub Discussions for questions and community discussion

Development Setup

If you'd like to contribute code, here's how to set up your development environment:

# 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 section 4 for details.

---

🌟 Design Philosophy

1. Minimal & Functional - Focus on content, not decoration
2. Developer First - Built by developers, for developers
3. Privacy Matters - No tracking, no data collection
4. Performance Obsessed - Every millisecond counts
5. Open & Transparent - Source-available core

---

📞 Support & Community

• Documentation: Coming soon
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

🙏 Acknowledgments

Built with:

• Next.js - React framework
• Tailwind CSS - Utility-first CSS
• FlexSearch - Full-text search

---

Made with 🔥 by the EmberDocs team