Skip to content

CLAUDE.md

Latest commit

 

History

History
76 lines (49 loc) · 3.58 KB

CLAUDE.md

File metadata and controls

76 lines (49 loc) · 3.58 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ember-cli-addon-docs is an Ember addon that generates documentation sites for other Ember addons. It provides components for building doc sites, a build pipeline that extracts API docs and search indexes, and a deploy pipeline for GitHub Pages.

Commands

  • Install: pnpm install
  • Dev server: pnpm start (serves dummy app at http://localhost:4200)
  • Build: pnpm build
  • Lint all: pnpm lint
  • Lint fix: pnpm lint:fix
  • Run all tests: pnpm test
  • Ember tests only: pnpm test:ember
  • Ember tests in watch mode: pnpm test:ember --server
  • Node tests only: pnpm test:node (mocha, runs tests in tests-node/)
  • Test app tests: pnpm test:test-apps (runs tests in test-apps/new-addon)

Uses pnpm as the package manager. The workspace includes test-apps/*.

Architecture

Build Pipeline (lib/)

The core build logic lives in index.js and lib/. During Ember's build process:

  1. index.js — Main addon entry point. Hooks into Ember CLI's treeForApp, treeForAddon, treeForPublic, and treeForVendor. Compiles markdown templates, extracts API docs via plugin registry, and builds a search index.

  2. lib/broccoli/ — Broccoli plugins for the build pipeline:

    • docs-compiler.js — Compiles extracted API documentation into JSON API format
    • search-indexer.js — Builds a lunr.js search index from docs and template content
    • docs-filter.js / hbs-content-filter.js — Broccoli filters for processing files

  3. lib/preprocessors/ — Template preprocessors:

    • markdown-template-compiler.js — Compiles .md files into Handlebars templates
    • hbs-content-extractor.js — Extracts content from HBS templates for search indexing

  4. lib/deploy/ — ember-cli-deploy plugin for deploying docs to GitHub Pages

  5. lib/models/plugin-registry.js — Registry for doc generation plugins (e.g., ember-cli-addon-docs-yuidoc)

Runtime Addon (addon/)

Ember Octane components and services that consuming addons use in their doc sites:

  • Components: docs-viewer, docs-header, docs-hero, docs-demo, docs-snippet, docs-code-highlight, api/ (API doc viewer components), etc.
  • Services: docs-routes (navigation), docs-search (lunr-based search), project-version (version management)
  • Styles: Uses Tailwind CSS 1.x compiled via PostCSS/Sass pipeline

App Re-exports (app/)

Standard Ember addon pattern — re-exports addon modules into the consuming app's namespace.

Blueprints (blueprints/)

  • ember-cli-addon-docs — Default blueprint run on ember install
  • docs-page — Generator for new documentation pages

Sandbox (sandbox/)

A "sandbox" addon used as a secondary documented project in the dummy app, demonstrating multi-project documentation support.

Tests

  • tests/ — Ember tests (acceptance, integration, unit) using QUnit, run via testem in Chrome
  • tests-node/ — Node.js unit tests using Mocha/Chai for the build pipeline code in lib/
  • test-apps/new-addon — Separate test app in the pnpm workspace

Key Concepts

  • Plugin system: API doc extraction is pluggable via addons with keyword ember-cli-addon-docs-plugin. The default plugin is ember-cli-addon-docs-yuidoc.
  • documentingAddonAt: Config option allowing a standalone app (not a dummy app) to document an addon at a specific path.
  • Version support: The addon manages doc versions for deployment, with a "latest" version concept (-latest).