Skip to content

Latest commit

 

History

History
234 lines (170 loc) · 8.51 KB

Setup.md

File metadata and controls

234 lines (170 loc) · 8.51 KB

EmberDocs Setup Guide

Goal: get a runnable EmberDocs instance locally in minutes.

Prerequisites

  • Node.js 18+ and npm.
  • Clone the repo and ensure docs/ is present for sample content.

Install & Configure

npm install
cp .env.example .env.local  # optional - customize branding/config
  • Keep .env.local private; never commit it.
  • All environment variables are optional - EmberDocs works with sensible defaults.
  • See .env.example for all available configuration options.

Homepage Behavior

By default, the root route (/) redirects to your documentation index (index.md). This means when users visit your deployed site, they'll see your documentation homepage immediately.

To show the EmberDocs framework marketing landing page instead:

  • Set EMBERDOCS_SHOW_LANDING=true in your .env.local
  • This is only needed for the EmberDocs framework repository itself

Default behavior (deployed instances):

  • / → redirects to /docs/index → shows your index.md content
  • This is the recommended setup for your own documentation site

Configuration Options

Theme Selection

Choose the visual theme for your documentation site:

# Theme options: dark (default), light
EMBERDOCS_THEME=light

Available themes:

  • dark (default): Developer-focused dark theme with terminal-style code blocks
  • light: Minimal, clean light theme with simple code blocks and feature cards
  • monochrome: Pure black-and-white minimalist theme with high contrast, no brand colors

The theme applies to both the landing page (if enabled) and all documentation pages. The default theme is dark if not specified.

Note: Theme selection is set via environment variable and applies site-wide. Users can still toggle between light/dark using the theme toggle button in the header (if available), but the initial/default theme is controlled by this setting.

Branding & Metadata

EmberDocs supports environment variables to customize branding and metadata throughout your documentation site:

# Default author name (used when document frontmatter doesn't specify an author)
EMBERDOCS_DEFAULT_AUTHOR="Your Company Name"

# Company or organization name (used in headers, metadata, and page titles)
EMBERDOCS_COMPANY_NAME="Your Company, Inc."

# Product name (used in headers, metadata, and page titles)
# Default: EmberDocs
EMBERDOCS_PRODUCT_NAME="Your Product Name"

# Primary URL for your company/product (used in links and metadata)
EMBERDOCS_PRIMARY_URL=https://example.com

How it works:

  • Author: If a document's frontmatter includes an author field, that value is used. Otherwise, EMBERDOCS_DEFAULT_AUTHOR is used (if set). If neither is set, no author is displayed.
  • Product/Company Name: These values are used in the site header, page titles, and metadata. If EMBERDOCS_COMPANY_NAME is set, page titles will be formatted as {PRODUCT_NAME} - {COMPANY_NAME} Documentation.
  • Primary URL: Can be used in links, footers, or other places where you need to reference your main website.

Logo Configuration

Add your custom logo to replace the default gradient logo mark:

# Path to your logo image (relative to /public directory)
# Supported formats: PNG, SVG, JPG
# Example: /logos/my-logo.png
EMBERDOCS_LOGO_PATH=/logos/your-logo.png

Steps:

  1. Place your logo file in the public folder (e.g., public/logos/my-logo.png)
  2. Set EMBERDOCS_LOGO_PATH to the path starting with / (relative to public)
  3. Restart your dev server

Tips: Logo displays at 28x28 pixels. SVG format works best. If not set, the default gradient logo mark is used.

See also: See brand/EMBERDOCS-STYLE-GUIDE.md for detailed logo setup instructions.

Navigation Links Configuration

Customize the header navigation menu with your own links:

# Header navigation links as JSON object
# Format: {"Label": "URL", "Another Label": "Another URL"}
EMBERDOCS_HEADER_LINKS={"Docs": "/docs", "Features": "/#features", "GitHub": "https://github.com/yourorg"}

Format: JSON object where keys are labels and values are URLs. External links must start with http:// or https://. Internal links start with /.

Default: If not set, EmberDocs uses: "Docs", "Features", and "GitHub"

See also: See brand/EMBERDOCS-STYLE-GUIDE.md for detailed examples and troubleshooting.

Footer Configuration

Add a footer to your documentation pages:

# Footer text content (e.g., copyright notice)
EMBERDOCS_FOOTER_TEXT=Your Company © 2025

# Footer links as JSON object (same format as header links)
EMBERDOCS_FOOTER_LINKS={"Privacy": "/privacy", "Terms": "/terms", "Contact": "/contact"}

Note: If both EMBERDOCS_FOOTER_TEXT and EMBERDOCS_FOOTER_LINKS are empty, no footer is displayed.

See also: See brand/EMBERDOCS-STYLE-GUIDE.md for detailed examples and troubleshooting.

Custom Documentation Path

By default, EmberDocs looks for documentation in docs/examples/. You can change this by setting the EMBERDOCS_CONTENT_DIR environment variable in .env.local:

# Use a different folder name
EMBERDOCS_CONTENT_DIR=docs/content

# Or use a completely different structure
EMBERDOCS_CONTENT_DIR=content
EMBERDOCS_CONTENT_DIR=pages
EMBERDOCS_CONTENT_DIR=markdown

Important: After changing EMBERDOCS_CONTENT_DIR, rebuild the search index:

npm run build:search

The folder structure you choose becomes your documentation structure:

  • docs/examples/getting-started/intro.md → /docs/getting-started/intro
  • docs/content/tutorials/basics.md → /docs/tutorials/basics
  • content/guides/advanced.md → /dev-docs/guides/advanced

Navigation automatically reflects your folder structure.

Custom Sidebar Ordering

By default, sidebar items are sorted alphabetically. You can customize the order by adding an order field to the frontmatter of your markdown files:

---
title: Getting Started
order: 1
---

# Getting Started
---
title: Installation
order: 2
---

# Installation

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
  • Within each group (ordered vs. unordered), the respective sorting applies

Example: If you have files with orders 1, 2, 3, and a file without an order field, the sidebar will show:

  1. File with order: 1
  2. File with order: 2
  3. File with order: 3
  4. File without order (alphabetically sorted)

This allows you to control sidebar order without renaming files.

Custom Documentation Base Route

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

# Use a different URL prefix
EMBERDOCS_BASE_ROUTE=/documentation  # URLs: /documentation/getting-started/intro
EMBERDOCS_BASE_ROUTE=/help           # URLs: /help/getting-started/intro
EMBERDOCS_BASE_ROUTE=/guides         # URLs: /guides/getting-started/intro

Note: The Next.js route structure uses /docs internally, but the EMBERDOCS_BASE_ROUTE setting uses rewrites to map your custom path to the internal route. This means:

  • Your files stay in the same location (controlled by EMBERDOCS_CONTENT_DIR)
  • Your URLs change (controlled by EMBERDOCS_BASE_ROUTE)
  • All links and navigation automatically use the custom base route

Example combination:

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

This would mean:

  • Files are in: content/getting-started/intro.md
  • URLs are: http://localhost:3000/documentation/getting-started/intro

Run Locally

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)

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.