Quick Start

Get up and running with EmberDocs in 5 minutes. This guide covers everything you need to start creating documentation.

Prerequisites

Before you begin, ensure you have:

• Node.js 18.0 or higher - Check with node --version
• npm or yarn - Check with npm --version
• Git - For cloning the repository

1. Clone and Install

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

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

2. Configure Environment Variables

Edit .env.local to customize your documentation site:

# Branding (optional but recommended)
EMBERDOCS_PRODUCT_NAME=My Documentation
EMBERDOCS_COMPANY_NAME=My Company, Inc.
EMBERDOCS_DEFAULT_AUTHOR=Your Name

# Logo (optional)
EMBERDOCS_LOGO_PATH=/logos/my-logo.png

# Navigation links (optional)
EMBERDOCS_HEADER_LINKS={"Docs": "/docs", "Features": "/#features", "GitHub": "https://github.com/yourorg"}

# Footer (optional)
EMBERDOCS_FOOTER_TEXT=My Company © 2025
EMBERDOCS_FOOTER_LINKS={"Privacy": "/privacy", "Terms": "/terms"}

# Custom documentation path (default: docs/examples)
# EMBERDOCS_CONTENT_DIR=docs/content

# Custom base route (default: /docs)
# EMBERDOCS_BASE_ROUTE=/documentation

Important: After editing .env.local, restart your dev server for changes to take effect.

3. Create Your First Document

By default, EmberDocs looks for documentation in docs/examples/. Create your first document:

# Create the directory if it doesn't exist
mkdir -p docs/examples

# Create your index page
touch docs/examples/index.md

Edit docs/examples/index.md:

---
title: "Welcome to My Documentation"
slug: "index"
date: "2026-01-02"
published: true
order: 0
---

# Welcome to My Documentation

This is your documentation homepage. You can write in standard Markdown.

## Features

- **Fast** - Static generation for instant page loads
- **Searchable** - Full-text search powered by FlexSearch
- **Beautiful** - Dark mode support with modern design
- **Flexible** - Organize content in folders with automatic navigation

## Getting Started

1. Add more markdown files to `docs/examples/`
2. Organize them in folders
3. Navigation is generated automatically
4. Use frontmatter to control ordering and metadata

## Next Steps

- Read the [Installation Guide](/docs/getting-started/installation)
- Learn [Basic Usage](/docs/guides/basic-usage)
- Explore [Customization](/docs/guides/customization)

Understanding Frontmatter

Every markdown file needs YAML frontmatter at the top (between --- delimiters). Here's what each field does:

Important: The slug field should match your file path structure:

• File: docs/examples/getting-started.md → slug: "getting-started"
• File: docs/examples/guides/basic-usage.md → slug: "guides/basic-usage"
• File: docs/examples/guides/advanced/index.md → slug: "guides/advanced" (not "guides/advanced/index")

Complete frontmatter example:

---
title: "Complete Guide to EmberDocs"
slug: "guides/complete-guide"
date: "2026-01-02"
tags: ["guide", "tutorial", "advanced"]
published: true
order: 5
author: "Jane Smith"
---

# Your content here

4. Start the Development Server

npm run dev

Open http://localhost:3000 in your browser. You'll see your documentation!

Note: The root route (/) redirects to /docs/index by default. To show the EmberDocs marketing landing page instead, set EMBERDOCS_SHOW_LANDING=true in .env.local.

Search Index: 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.

5. Add More Documents

Create additional markdown files in docs/examples/:

# Create a getting started guide
touch docs/examples/getting-started.md

Edit docs/examples/getting-started.md:

---
title: "Getting Started"
slug: "getting-started"
date: "2026-01-02"
published: true
order: 1
---

# Getting Started

This is a new documentation page!

## What You Can Do

- Write in Markdown
- Use code blocks with syntax highlighting
- Create links to other pages
- Organize content in folders

## Markdown Features

EmberDocs supports all standard Markdown plus GitHub Flavored Markdown (GFM):

### Code Blocks

\`\`\`typescript
function greet(name: string): string {
  return `Hello, ${name}!`;
}
\`\`\`

### Tables

| Feature | Status | Notes |
|---------|--------|-------|
| Search | ✅ | FlexSearch powered |
| Dark Mode | ✅ | Auto-detects preference |
| Versioning | 🚧 | Coming soon |

### Blockquotes

> This is a blockquote. Use it for callouts, warnings, or important notes.

### Links

- [Internal link](/docs/getting-started/installation)
- [External link](https://example.com)
- [Link with text](https://example.com "Hover text")

### Images

![Alt text](/images/screenshot.png "Optional title")

### Task Lists

- [x] Completed task
- [ ] Incomplete task
- [x] Another completed task

The page will automatically appear in the sidebar navigation. The URL will be /docs/getting-started (based on the slug field).

6. Organize with Folders

Create folders to organize your documentation:

# Create a guides folder
mkdir -p docs/examples/guides

# Create an index.md for the folder
touch docs/examples/guides/index.md

# Create a guide
touch docs/examples/guides/basic-usage.md

Edit docs/examples/guides/index.md:

---
title: "Guides"
slug: "guides"
date: "2026-01-02"
published: true
order: 2
---

# Guides

This is the guides section. All guides are listed here.

Important: When you create a folder with an index.md file:

• The URL is /docs/guides (not /docs/guides/index)
• The slug in frontmatter should be "guides" (not "guides/index")
• The folder appears as a collapsible section in the sidebar
• All files in the folder appear as children in the navigation

Example folder structure:

docs/examples/
├── index.md                    # /docs/index
├── getting-started.md          # /docs/getting-started
├── guides/
│   ├── index.md                # /docs/guides
│   ├── basic-usage.md          # /docs/guides/basic-usage
│   └── advanced/
│       ├── index.md            # /docs/guides/advanced
│       └── features.md         # /docs/guides/advanced/features

The folder structure automatically creates navigation hierarchy in the sidebar.

7. Use Search

Search is built-in and works automatically:

1. Press ⌘K (Mac) or Ctrl+K (Windows/Linux) to open the search palette
2. Type your query
3. Results appear instantly with excerpts
4. Click a result to navigate to that page

The search index is built from all your markdown files and includes:

• Document titles
• Body content
• Headings
• Excerpts for preview

8. Customize Sidebar Order

Control the order of items in the sidebar using the order field in frontmatter:

---
title: "First Page"
order: 1
---

# First Page

---
title: "Second Page"
order: 2
---

# Second Page

Sorting rules:

• Items with order values are sorted numerically (lower numbers first)
• Items without order are sorted alphabetically after ordered items
• Folders always appear before documents in the same parent

9. Customize Your Branding

Add Your Logo

1. Place your logo in public/logos/my-logo.png
2. Set in .env.local:
   bashCopy

   EMBERDOCS_LOGO_PATH=/logos/my-logo.png

3. Restart the dev server

Supported formats: PNG, SVG, JPG
Display size: 28x28 pixels (larger images are scaled)
Best format: SVG for crisp display

Change Product/Company Name

EMBERDOCS_PRODUCT_NAME=My Awesome Product
EMBERDOCS_COMPANY_NAME=My Company, Inc.

Customize Navigation

EMBERDOCS_HEADER_LINKS={"Docs": "/docs", "Blog": "/blog", "GitHub": "https://github.com/yourorg"}

Add Footer

EMBERDOCS_FOOTER_TEXT=My Company © 2025
EMBERDOCS_FOOTER_LINKS={"Privacy": "/privacy", "Terms": "/terms"}

See the Customization Guide for detailed instructions.

Common Tasks

Add a New Page

1. Create a new .md file in docs/examples/ (or your custom content directory)
2. Add frontmatter with required fields:
   markdownCopy

   ---
   title: "Page Title"
   slug: "page-slug"
   published: true
   ---

3. Write your content in Markdown
4. Save and refresh your browser - the page appears automatically!

Create Nested Folders

# Create nested structure
mkdir -p docs/examples/guides/advanced

# Add index.md to the folder
touch docs/examples/guides/advanced/index.md

The URL will be /docs/guides/advanced (without /index).

Change Documentation Path

If you want to use a different folder for your docs:

# In .env.local
EMBERDOCS_CONTENT_DIR=docs/content

Then rebuild the search index:

npm run build:search

Change Base Route

To serve docs at a different URL path:

# In .env.local
EMBERDOCS_BASE_ROUTE=/documentation

Now your docs will be at /documentation/* instead of /docs/*.

Enable Dark Mode

Dark mode is built-in and automatically detects system preference. Users can toggle it using the theme toggle button in the header.

To force dark mode programmatically:

document.documentElement.setAttribute('data-theme', 'dark');

Project Structure

emberdocs/
├── docs/
│   └── examples/          # Your documentation files (default)
│       ├── index.md       # Homepage
│       ├── getting-started/
│       └── guides/
├── src/
│   ├── app/               # Next.js App Router
│   │   └── docs/          # Documentation routes
│   ├── lib/               # Core functionality
│   │   ├── content.ts     # Markdown parsing
│   │   ├── search.ts      # Search indexing
│   │   └── navigation.ts  # Sidebar generation
│   └── components/        # React components
├── public/                # Static assets (logos, etc.)
├── .env.local             # Your configuration (not committed)
└── package.json           # Dependencies and scripts

Available Commands

Development workflow:

# Start dev server
npm run dev

# In another terminal, add/edit documentation files
# Then rebuild search index if needed
npm run build:search

# Before committing, run full check
npm run check

Troubleshooting

Search doesn't work

Symptoms: Search palette opens but shows "No results" or doesn't open at all.

Solution: Build the search index:

npm run build:search

Verify: Check that public/search-index.json exists and has content.

Note: The search index is automatically built during npm run build, but for development you may need to build it manually after adding new documents.

Changes to .env.local don't appear

Solution: Restart your dev server. Environment variables are only loaded at startup:

# Stop server (Ctrl+C)
npm run dev

Why: Next.js reads environment variables when the server starts, not on file changes.

Page shows 404

Possible causes:

1. File doesn't exist in docs/examples/ (or your custom content directory)
2. Frontmatter slug doesn't match the file path
3. published: false in frontmatter (page is hidden)
4. Search index needs rebuilding
5. File path doesn't match URL structure

Solution:

• Check file exists: ls docs/examples/your-file.md
• Verify frontmatter slug matches expected URL:
  • File: docs/examples/guides/basic.md → slug: "guides/basic"
  • File: docs/examples/guides/advanced/index.md → slug: "guides/advanced"
• Check published: true in frontmatter
• Rebuild search index: npm run build:search
• Restart dev server
• Check browser console for errors

Sidebar order is wrong

Solution: Add order field to frontmatter:

---
title: "My Page"
order: 1
---

Sorting rules:

• Lower numbers appear first
• Items without order are sorted alphabetically after ordered items
• Folders always appear before documents in the same parent
• Within each group (ordered vs. unordered), the respective sorting applies

Logo doesn't show

Checklist:

• ✅ File exists in public/ folder (e.g., public/logos/my-logo.png)
• ✅ Path in .env.local starts with / (e.g., /logos/my-logo.png)
• ✅ File name uses lowercase, no spaces (e.g., my-logo.png not My Logo.png)
• ✅ Dev server was restarted after editing .env.local
• ✅ File format is PNG, SVG, or JPG
• ✅ Check browser console for 404 errors

Navigation not updating

Symptoms: New files don't appear in sidebar after creating them.

Solution:

1. Ensure file has valid frontmatter with title and slug
2. Check published: true (or omit it, defaults to true)
3. Restart dev server: npm run dev
4. Hard refresh browser (Cmd+Shift+R / Ctrl+Shift+R)

Build fails

Common errors:

"Cannot find module 'flexsearch'"

npm install flexsearch

"Document path not found"

• Check file paths are correct
• Ensure files have .md extension
• Verify frontmatter is valid YAML

"Build timeout"

• Increase timeout in next.config.js:

export default {
  staticPageGenerationTimeout: 300, // seconds
};

TypeScript errors

Solution:

# Check for type errors
npm run typecheck

# Clear Next.js cache
rm -rf .next

# Rebuild
npm run build

Port already in use

Solution: Use a different port:

npm run dev -- -p 3001

Or kill the process using port 3000:

# Find process
lsof -ti:3000

# Kill it
kill -9 $(lsof -ti:3000)

Next Steps

• Learn the basics: Basic Usage Guide
• Customize everything: Customization Guide
• Explore the API: API Reference
• Get help: Troubleshooting Guide

Deployment

Deploy to Vercel

1. Push your code to GitHub
2. Import project in Vercel
3. Add environment variables in Vercel dashboard
4. Deploy automatically on every push

Required environment variables in Vercel:

• All your .env.local variables (except secrets)
• EMBERDOCS_CONTENT_DIR (if custom)
• EMBERDOCS_BASE_ROUTE (if custom)

Deploy to Netlify

1. Push your code to GitHub
2. Import project in Netlify
3. Build command: npm run build
4. Publish directory: .next
5. Add environment variables in Netlify dashboard

Self-Hosted Deployment

# Build for production
npm run build

# Start production server
npm run start

Production considerations:

• Set NODE_ENV=production
• Use a process manager (PM2, systemd)
• Set up reverse proxy (nginx, Caddy)
• Configure SSL/TLS certificates
• Set up monitoring and logging

Build Optimization

Before deploying, optimize your build:

# Test production build locally
npm run build
npm run start

Note: For bundle size analysis, you can use @next/bundle-analyzer (not included by default). Install it separately if needed.

Tips:

• Keep images optimized (use Next.js Image component)
• Minimize dependencies
• Use dynamic imports for heavy components
• Enable compression in your server

Understanding URLs and File Paths

EmberDocs maps file paths to URLs automatically:

Key rules:

• The slug should match the file path relative to your content directory
• Folders with index.md use the folder name as the slug (not folder/index)
• URLs are always lowercase and use forward slashes
• Special characters in filenames should be avoided (use hyphens instead)

Markdown Best Practices

Headings

Use proper heading hierarchy (H1 → H2 → H3):

# Main Title (H1 - only one per page)

## Section (H2)

### Subsection (H3)

#### Detail (H4)

Code Blocks

Always specify language for syntax highlighting:

\`\`\`typescript
// TypeScript code
\`\`\`

\`\`\`bash
# Shell commands
\`\`\`

\`\`\`json
{
  "key": "value"
}
\`\`\`

Links

Use relative paths for internal links:

✅ Good: [Installation](/docs/getting-started/installation)
❌ Bad: [Installation](http://localhost:3000/docs/getting-started/installation)

Images

Place images in public/ and reference with absolute paths:

![Screenshot](/images/screenshot.png)

Tables

Use tables for structured data:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

Need Help?

• Setup issues: Check the Installation Guide
• Configuration: Review Configuration Reference for all options
• Usage questions: Read Basic Usage Guide
• Customization: See Customization Guide
• Troubleshooting: Check Troubleshooting Guide
• Search: Use ⌘K / Ctrl+K to search the docs
• GitHub: Visit the GitHub repository for issues and discussions