/craft:site:create - Full Documentation Site Wizard

You are an ADHD-friendly documentation site creator. One command to go from zero to a deployed, professionally designed documentation site.

Purpose

The "zero to deployed" solution for documentation sites:

• Detects project type and recommends framework
• Applies consistent design through presets
• Creates starter content with proper templates
• Sets up navigation and deployment

Usage

/craft:site:create                      # Interactive wizard
/craft:site:create --preset data-wise   # Use preset directly
/craft:site:create --quick              # Minimal prompts (auto-detect all)
/craft:site:create --from template      # From template repo (future)

When Invoked

Step 1: Project Detection

# Detect project type
ls pyproject.toml package.json DESCRIPTION Cargo.toml go.mod 2>/dev/null

# Get project name
basename $(pwd)

# Get git info
git remote get-url origin 2>/dev/null

Display:

┌─────────────────────────────────────────────────────────────┐
│ /craft:site:create                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ 🚀 DOCUMENTATION SITE WIZARD                                │
│                                                             │
│ Step 1/5: Project Detection                                 │
│                                                             │
│   Project: aiterm                                           │
│   Type: Python Package (pyproject.toml)                     │
│   Repo: https://github.com/Data-Wise/aiterm                 │
│                                                             │
│   Recommended: MkDocs with Material theme                   │
│                                                             │
│ Continue? (Y/n)                                             │
└─────────────────────────────────────────────────────────────┘

Step 2: Design Preset Selection

If not specified via --preset:

┌─────────────────────────────────────────────────────────────┐
│ Step 2/5: Design Preset                                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ Choose your site's design language:                         │
│                                                             │
│ STANDARD PRESETS:                                           │
│                                                             │
│   [1] data-wise (Recommended)                               │
│       DT's standard - Material + custom styling             │
│       Colors: Blue primary (#1a73e8), orange accent         │
│       Features: Tabs, dark mode, code copy                  │
│                                                             │
│   [2] minimal                                               │
│       Clean and simple, fast loading                        │
│       Colors: Neutral grays                                 │
│       Features: Essential only                              │
│                                                             │
│   [3] open-source                                           │
│       Community-friendly with badges                        │
│       Colors: GitHub-inspired blue/green                    │
│       Features: Contributors, changelog visible             │
│                                                             │
│   [4] corporate                                             │
│       Professional and formal                               │
│       Colors: Customizable brand colors                     │
│       Features: Version selector, enterprise look           │
│                                                             │
│ ADHD-FRIENDLY PRESETS:                                      │
│                                                             │
│   [5] adhd-focus                                            │
│       Calm forest green, minimal distractions               │
│       Colors: Green (#2d6a4f), sage accent                  │
│       Features: Reduced animations, clear hierarchy         │
│                                                             │
│   [6] adhd-calm                                             │
│       Warm earth tones, cozy reading experience             │
│       Colors: Brown (#8b5a2b), terracotta accent            │
│       Features: Cream backgrounds, soft contrasts           │
│                                                             │
│   [7] adhd-dark                                             │
│       Dark-first, reduced eye strain                        │
│       Colors: Muted sage (#7c9885), dark backgrounds        │
│       Features: No light mode, night reading optimized      │
│                                                             │
│   [8] adhd-light                                            │
│       Warm light, never harsh white                         │
│       Colors: Blue-gray (#5a6e78), warm off-white           │
│       Features: Soft shadows, sepia undertones              │
│                                                             │
│   [9] custom                                                │
│       Configure colors, fonts, features manually            │
│                                                             │
│ Select (1-9):                                               │
└─────────────────────────────────────────────────────────────┘

Step 3: Branding

┌─────────────────────────────────────────────────────────────┐
│ Step 3/5: Branding                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ Site name: AITerm                                           │
│   (from project name, edit? y/N)                            │
│                                                             │
│ Tagline: [auto-detect from pyproject.toml description]      │
│   "AI Terminal Optimizer for Claude Code workflows"         │
│   (edit? y/N)                                               │
│                                                             │
│ Logo: (none detected)                                       │
│   [1] Use text logo (Recommended)                           │
│   [2] Provide logo path                                     │
│   [3] Skip for now                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Step 4: Navigation Structure

┌─────────────────────────────────────────────────────────────┐
│ Step 4/5: Navigation Structure                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ Choose your documentation structure:                        │
│                                                             │
│   [1] Standard (Recommended for most projects)              │
│       Home | Quick Start | Reference | Guide | API          │
│                                                             │
│   [2] Tutorial-focused                                      │
│       Home | Tutorial | How-to | Reference | Explanation    │
│                                                             │
│   [3] Minimal                                               │
│       Home | Quick Start | Reference                        │
│                                                             │
│   [4] CLI-focused (Recommended for aiterm)                  │
│       Home | Quick Start | Commands | Guide | Config        │
│                                                             │
│ Select (1-4):                                               │
└─────────────────────────────────────────────────────────────┘

Step 5: Content Generation

┌─────────────────────────────────────────────────────────────┐
│ Step 5/5: Creating Your Site                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ Creating files...                                           │
│                                                             │
│   ✓ mkdocs.yml (configuration)                              │
│   ✓ docs/index.md (home page with features)                 │
│   ✓ docs/QUICK-START.md (30-second guide)                   │
│   ✓ docs/REFCARD.md (quick reference)                       │
│   ✓ docs/getting-started/installation.md                    │
│   ✓ docs/guide/overview.md                                  │
│   ✓ docs/reference/commands.md                              │
│   ✓ .github/workflows/docs.yml (deployment)                 │
│   ✓ .craft/site-design.yaml (design config)                 │
│                                                             │
│ Building preview...                                         │
│   ✓ Site builds successfully                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Design Presets

data-wise (Default for DT)

# .craft/site-design.yaml
preset: "data-wise"

branding:
  name: "{PROJECT_NAME}"
  tagline: "{PROJECT_DESCRIPTION}"
  logo: null  # Use text logo

colors:
  primary: "#1a73e8"
  accent: "#ff6b35"
  scheme: "auto"  # light/dark/auto

navigation:
  style: "tabs"
  max_depth: 3
  sections:
    - name: "Home"
      icon: "home"
    - name: "Quick Start"
      icon: "rocket"
    - name: "Reference"
      icon: "code"
    - name: "Guide"
      icon: "book"

features:
  search: true
  dark_mode: true
  code_copy: true
  edit_on_github: true
  navigation_instant: true
  navigation_tracking: true
  version_selector: false

mkdocs.yml generated:

site_name: {PROJECT_NAME}
site_description: {PROJECT_DESCRIPTION}
site_url: https://{USERNAME}.github.io/{REPO}/

repo_name: {USERNAME}/{REPO}
repo_url: https://github.com/{USERNAME}/{REPO}
edit_uri: edit/main/docs/

theme:
  name: material
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.action.edit
  icon:
    repo: fontawesome/brands/github

extra_css:
  - stylesheets/extra.css

plugins:
  - search
  - minify:
      minify_html: true

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - admonition
  - pymdownx.details
  - tables
  - toc:
      permalink: true
  - attr_list
  - md_in_html

nav:
  - Home: index.md
  - Quick Start: QUICK-START.md
  - Reference Card: REFCARD.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Configuration: getting-started/configuration.md
  - Guide:
    - Overview: guide/overview.md
  - Reference:
    - Commands: reference/commands.md
    - Configuration: reference/configuration.md

⚡ Mermaid Integration (Native):

Per Material for MkDocs documentation, Mermaid is handled natively through the superfences extension.

No extra_javascript needed! The configuration above is complete.

Why no CDN?

• Material for MkDocs integrates Mermaid natively
• Adding a CDN manually causes double initialization
• Can create version conflicts and theme styling issues
• Native integration "works with instant loading" automatically

Only add extra_javascript if:

• You need custom Mermaid configuration (ELK layouts, etc.)
• Using a non-Material theme

For custom config (advanced users only):

extra_javascript:
  - javascripts/mermaid-config.js

// javascripts/mermaid-config.js
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' });

minimal

preset: "minimal"

colors:
  primary: "#424242"
  accent: "#1976d2"
  scheme: "default"

features:
  search: true
  dark_mode: false
  code_copy: true
  edit_on_github: false
  navigation_instant: false
  navigation_tracking: false

open-source

preset: "open-source"

colors:
  primary: "#0366d6"
  accent: "#28a745"
  scheme: "auto"

features:
  search: true
  dark_mode: true
  code_copy: true
  edit_on_github: true
  navigation_instant: true
  version_selector: false

badges:
  - pypi
  - license
  - tests
  - coverage

corporate

preset: "corporate"

colors:
  primary: "#003366"  # Customizable
  accent: "#0066cc"
  scheme: "default"

features:
  search: true
  dark_mode: false
  code_copy: true
  edit_on_github: false
  version_selector: true
  announcement_bar: true

Page Templates

index.md Template

# {PROJECT_NAME}

{BADGES}

> {TAGLINE}

## Features

<div class="grid cards" markdown>

- :rocket: **Quick Setup**

    Get started in 30 seconds with our streamlined installation.

- :sparkles: **Feature 2**

    Description of key feature.

- :zap: **Feature 3**

    Description of key feature.

- :shield: **Feature 4**

    Description of key feature.

</div>

## Quick Start

```bash
{INSTALL_COMMAND}

{FIRST_COMMAND}

Documentation

• Quick Start - Get running in 30 seconds
• Reference Card - Quick command reference
• Full Guide - Complete documentation

Links

• GitHub
• PyPI
• Changelog

### QUICK-START.md Template

```markdown
# Quick Start

Get up and running in 30 seconds.

## Install

=== "Homebrew (macOS)"

    ```bash
    brew install {HOMEBREW_TAP}/{PROJECT_NAME}
    ```

=== "pip"

    ```bash
    pip install {PYPI_NAME}
    ```

=== "uv"

    ```bash
    uv tool install {PYPI_NAME}
    ```

## Verify

```bash
{PROJECT_NAME} --version

First Command

{FIRST_COMMAND}

Expected output:

{EXPECTED_OUTPUT}

Next Steps

• Full Guide - Complete documentation
• Reference Card - Quick command reference
• Configuration - Customize your setup

### REFCARD.md Template

```markdown
# Quick Reference

┌─────────────────────────────────────────────────────────────┐ │ {PROJECT_NAME} QUICK REFERENCE │ ├─────────────────────────────────────────────────────────────┤ │ Version: {VERSION} │ │ Docs: {DOCS_URL} │ └─────────────────────────────────────────────────────────────┘

## Essential Commands

| Command | Description |
|---------|-------------|
| `{cmd1}` | {desc1} |
| `{cmd2}` | {desc2} |
| `{cmd3}` | {desc3} |

## Common Workflows

### Workflow 1: {Name}

```bash
# Step 1
{command}

# Step 2
{command}

Workflow 2: {Name}

{command}

Configuration

Setting	Default	Description
{setting1}	{default1}	{desc1}

Troubleshooting

Issue	Solution
{issue1}	{solution1}

Links

• Full Documentation
• GitHub Issues

## Files Created

project/ ├── mkdocs.yml # Site configuration ├── .craft/ │ └── site-design.yaml # Design settings ├── docs/ │ ├── index.md # Home page │ ├── QUICK-START.md # 30-second guide │ ├── REFCARD.md # Quick reference │ ├── CHANGELOG.md # (symlink or copy) │ ├── getting-started/ │ │ ├── installation.md │ │ └── configuration.md │ ├── guide/ │ │ └── overview.md │ ├── reference/ │ │ ├── commands.md │ │ └── configuration.md │ └── stylesheets/ │ └── extra.css # Custom styles ├── .github/ │ └── workflows/ │ └── docs.yml # Deployment workflow └── requirements-docs.txt # MkDocs dependencies

## Output

┌─────────────────────────────────────────────────────────────┐ │ ✅ DOCUMENTATION SITE CREATED │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Preset: data-wise │ │ Framework: MkDocs Material │ │ │ │ Created: │ │ • mkdocs.yml (site configuration) │ │ • docs/ (9 pages) │ │ • .github/workflows/docs.yml (deployment) │ │ • .craft/site-design.yaml (design settings) │ │ │ │ Quick commands: │ │ Preview: mkdocs serve │ │ Build: mkdocs build │ │ Deploy: mkdocs gh-deploy │ │ │ │ Or use craft commands: │ │ /craft:site:preview │ │ /craft:site:build │ │ /craft:site:deploy │ │ │ │ What's next? │ │ → Edit docs/index.md with your content │ │ → Run mkdocs serve to preview │ │ → Push to GitHub to auto-deploy │ └─────────────────────────────────────────────────────────────┘

## Mermaid Diagram Best Practices

Per [official Mermaid documentation](https://mermaid.js.org/syntax/flowchart.html), follow these guidelines when adding diagrams to your site:

### ✅ Use Markdown Strings (Not `<br/>` tags)

**❌ Avoid:**
```markdown
```mermaid
flowchart TD
    A[Getting Started<br/>7 steps]    ❌ Manual line breaks

**✅ Recommended:**
```markdown
```mermaid
flowchart TD
    A["`**Getting Started**
    7 steps · 10 minutes`"]           ✅ Auto-wraps, supports **bold**

**Benefits:**
- Automatic text wrapping at node width
- Supports **bold**, *italic*, `code` formatting
- Better mobile responsiveness
- More maintainable

### Other Best Practices

1. **Prefer `flowchart` over `graph`** - Clearer intent (both work identically)
2. **Use vertical layouts (TD)** - Better mobile rendering than horizontal (LR)
3. **Capitalize "end" keyword** - Use "End" or "END" to avoid breaking diagrams
4. **Connect all nodes** - Orphaned nodes cause syntax errors
5. **Keep it simple** - Avoid over-engineering diagrams

**See also:** `/craft:docs:mermaid-linter` skill for validation

## Quick Mode (`--quick`)

Skips all prompts and uses detected/default values:

```bash
/craft:site:create --quick

Defaults:

• Preset: data-wise
• Name: from project config
• Tagline: from project config
• Structure: auto-detected based on project type

Integration

This command is Phase 1 of the site command redesign.

Replaces: /craft:site:init (which remains for basic init only)

Related commands:

• /craft:site:update - Update content from code changes
• /craft:site:status - Dashboard and health check
• /craft:site:theme - Quick theme changes
• /craft:site:deploy - Deploy to GitHub Pages

ADHD-Friendly Features

1. One command - No need to remember multiple commands
2. Smart defaults - Everything auto-detected when possible
3. Visual wizard - Clear steps with progress indicator
4. Immediate result - Site builds and previews automatically
5. Next steps - Always shows what to do next