# Help System

This directory contains the help system implementation for the Quick API application.

## Overview

The help system provides contextual assistance to users through a panel-based interface. It supports:

- **Categories**: Help topics are organized into categories (general, taxonomy, entity, model, namespace, property, association, function)
- **Search**: Full-text search across titles, body content, and examples
- **Examples**: Flexible examples format supporting both legacy string format and new array format with optional titles
- **Links**: Related links to external resources

## Help Topic Structure

Each help topic follows this structure:

```typescript
interface HelpTopic {
  id: string                    // Unique identifier within the category
  category: string              // Topic category
  title: string                 // Display title
  body: string                  // Main content (Markdown format)
  examples?: string | HelpExample[]  // Optional examples (see below)
  links?: HelpLink[]            // Optional related links
}
```

## Examples Format

The `examples` field supports two formats for backward compatibility and enhanced functionality:

### Legacy String Format (Backward Compatible)

```yaml
examples: |
  ```
  // Simple example in code block
  const example = "This is a string example"
  ```
```

### New Array Format (Enhanced)

```yaml
examples:
  - title: "Basic Example"
    value: |
      ```
      // Example with title
      const basic = "Basic usage"
      ```
  - title: "Advanced Example"
    value: |
      ```
      // More complex example
      const advanced = {
        feature: "Advanced usage",
        complexity: "High"
      }
      ```
  - value: |
      ```
      // Example without title
      const simple = "No title needed"
      ```
```

### HelpExample Interface

```typescript
interface HelpExample {
  title?: string    // Optional title for the example
  value: string     // The example content (Markdown format)
}
```

## Benefits of the New Format

1. **Better Organization**: Examples can be grouped with descriptive titles
2. **Improved Readability**: Multiple examples can be clearly separated
3. **Backward Compatibility**: Existing help topics continue to work
4. **Enhanced Search**: Search functionality works with both example titles and content
5. **Flexible**: Examples can have titles or not, depending on needs

## Implementation Details

- **Help Panel**: Renders both formats correctly with proper titles
- **Search Service**: Searches both example titles and content
- **Type Safety**: Full TypeScript support for both formats
- **Testing**: Comprehensive tests for both formats

## Best Practices

- Use descriptive titles for examples when they add value
- Keep examples concise but meaningful
- Use code blocks for code examples
- Include practical, real-world examples
- Consider the user's skill level when writing examples
