site

Spectrum Design Data Documentation Site

The documentation site for Spectrum Design Data, built with 11ty (Eleventy).

Overview

This site serves documentation for:

• Components: Component API schemas and options
• Tokens: Design tokens with resolved values and alias links
• Registry: Design system registry entries (sizes, states, variants, glossary, etc.)

The site is built from markdown files generated by the markdown-generator tool, which converts structured data from @adobe/spectrum-tokens, @adobe/spectrum-component-api-schemas, and @adobe/design-system-registry into markdown with YAML frontmatter.

Local Development

Prerequisites

• Node.js ~20.12
• pnpm@10.17.1

Setup

# Install dependencies (from monorepo root)
pnpm install

# Generate markdown files
moon run markdown-generator:generate

# Copy generated markdown to site source
moon run site:copyContent

# Start development server
moon run site:start

The site will be available at http://localhost:8080/spectrum-design-data/.

Development Workflow

1. Make changes to source files in src/
2. The development server will automatically reload
3. For changes to generated markdown, regenerate and copy:

   moon run markdown-generator:generate
   moon run site:copyContent

Build Process

The build pipeline consists of several steps:

1. Generate Markdown: moon run markdown-generator:generate

   • Converts tokens, components, and registry data to markdown
   • Outputs to tools/markdown-generator/output/

2. Copy Content: moon run site:copyContent

   • Copies generated markdown to docs/site/src/components/, src/tokens/, src/registry/
   • These files are gitignored but processed by 11ty

3. Build Site: moon run site:build

   • 11ty processes markdown files and templates
   • Generates static HTML in ../../site/

4. Export: moon run site:export

   • Final export step for deployment
   • Outputs to ../../site/ directory

Build Commands

# Full build pipeline
moon run site:export

# Individual steps
moon run markdown-generator:generate
moon run site:copyContent
moon run site:build
moon run site:export

Project Structure

docs/site/
├── src/
│   ├── assets/          # CSS and static assets
│   ├── components/      # Generated component markdown (gitignored)
│   ├── data/            # Site metadata and navigation
│   ├── layouts/         # 11ty layout templates (Liquid)
│   ├── pages/           # Static pages and index pages
│   ├── registry/        # Generated registry markdown (gitignored)
│   └── tokens/          # Generated token markdown (gitignored)
├── public/              # Static files (favicon, schemas)
├── scripts/             # Build scripts
├── eleventy.config.js   # 11ty configuration
└── package.json

Configuration

11ty Configuration

The eleventy.config.js file configures:

• Input: src/ directory
• Output: ../../site/ directory
• Path Prefix: /spectrum-design-data (for GitHub Pages)
• Collections: components, tokens, registry (from generated markdown)
• Git Ignore: Disabled (setUseGitIgnore(false)) to process generated markdown files

Generated Markdown

Generated markdown files in src/components/, src/tokens/, and src/registry/ are:

• Created by markdown-generator tool
• Copied during copyContent task
• Gitignored (in .gitignore)
• Processed by 11ty despite being gitignored

Deployment

The site is deployed to GitHub Pages via .github/workflows/deploy-docs.yml:

1. Cleans the site directory
2. Generates markdown files
3. Builds and exports the 11ty site
4. Builds other documentation apps (visualizer, viewer, etc.)
5. Uploads and deploys to GitHub Pages

Deployment Workflow

- moon run site:clean          # Clean site directory
- moon run markdown-generator:generate  # Generate markdown
- moon run site:export         # Build and export site

Migration from Next.js

This site was migrated from Next.js to 11ty for:

• Simpler static site generation: 11ty is purpose-built for static sites
• Better markdown support: Native markdown processing with frontmatter
• Reduced dependencies: Fewer npm packages, faster builds
• Chatbot indexing: Generated markdown is published to docs-markdown branch

The migration included:

• Replacing Next.js pages with 11ty layouts and collections
• Converting React components to Liquid templates
• Updating build pipeline to use 11ty
• Removing React/Next.js dependencies

Troubleshooting

Generated markdown not appearing

1. Ensure markdown generator ran: moon run markdown-generator:generate
2. Copy content: moon run site:copyContent
3. Check that files exist in src/components/, src/tokens/, src/registry/

Build errors

1. Check that all dependencies are installed: pnpm install
2. Verify source packages are available:
   • @adobe/spectrum-tokens
   • @adobe/spectrum-component-api-schemas
   • @adobe/design-system-registry
3. Clean and rebuild: moon run site:clean && moon run site:export

Development server not starting

1. Ensure port 8080 is available
2. Check that markdown files are copied: moon run site:copyContent
3. Verify 11ty is installed: pnpm list @11ty/eleventy

Related Tools

• Markdown Generator (tools/markdown-generator/): Generates markdown from source data
• Publish Markdown Workflow (.github/workflows/publish-markdown.yml): Publishes markdown to docs-markdown branch for chatbot indexing