path: root/SHORTCODES.md

# Shortcodes Documentation - danix.xyz

The danix.xyz theme provides four essential shortcodes for extending and enhancing your content. All shortcodes support multilingual content through Hugo's i18n framework, ensuring seamless language switching across your site.

## Gravatar

Display an avatar from Gravatar based on an email address hash. This shortcode retrieves the user's profile image directly from the Gravatar service, perfect for author bios, team pages, and contributor profiles.

### Syntax

```
{{< gravatar email="user@example.com" >}}
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| email | Yes | Email address for Gravatar lookup |
| size | No | Avatar size in pixels (default: 256) |
| alt | No | Alt text for accessibility (default: "User avatar") |
| class | No | Custom CSS classes (default: "w-32 h-32 rounded-full") |

### Example

Basic usage:
```
{{< gravatar email="danix@danix.xyz" >}}
```

With custom styling:
```
{{< gravatar email="danix@danix.xyz" alt="Danilo Profile" class="w-48 h-48 rounded-full border-4 border-accent" >}}
```

## Image

Display a responsive image with optional caption and automatic lazy-loading. Images are optimized for all screen sizes and support accessibility best practices.

### Syntax

```
{{< image src="/path/to/image.jpg" alt="Description" caption="Optional caption" >}}
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| src | Yes | Path or URL to the image file |
| alt | No | Alt text for accessibility |
| caption | No | Optional caption displayed below the image |
| class | No | Custom CSS classes (default: "w-full h-auto rounded-lg border border-border/30"). Overrides all defaults when specified. |

### Example

Basic usage:
```
{{< image src="/images/mountain.jpg" alt="Mountain landscape" >}}
```

With caption:
```
{{< image src="/images/mountain.jpg" alt="Mountain landscape" caption="Hiking in the Alps" >}}
```

With custom sizing and styling:
```
{{< image src="/images/mountain.jpg" alt="Mountain landscape" class="w-2/3 mx-auto rounded-lg shadow-lg border-2 border-accent" >}}
```

### Common CSS Classes for Image Sizing

Use Tailwind CSS utility classes to customize image appearance:

#### Width & Layout
| Class | Effect |
|-------|--------|
| `w-full` | Full container width (default) |
| `w-1/2` | 50% width |
| `w-2/3` | 66% width |
| `w-3/4` | 75% width |
| `max-w-lg` | Max 512px width |
| `max-w-2xl` | Max 672px width |
| `max-w-3xl` | Max 768px width |
| `mx-auto` | Center horizontally |

#### Height & Aspect Ratio
| Class | Effect |
|-------|--------|
| `h-auto` | Auto height (maintains aspect ratio) |
| `aspect-video` | 16:9 aspect ratio |
| `aspect-square` | 1:1 aspect ratio |
| `aspect-[3/2]` | 3:2 aspect ratio |
| `object-cover` | Fill container, crop if needed |
| `object-contain` | Fit entire image in container |

#### Borders & Shadows
| Class | Effect |
|-------|--------|
| `rounded-lg` | Large rounded corners (default) |
| `rounded-xl` | Extra large rounded corners |
| `border-2` | 2px border |
| `border-accent` | Accent color border |
| `border-border/50` | Semi-transparent border |
| `shadow-lg` | Large drop shadow |
| `shadow-xl` | Extra large drop shadow |

#### Examples

Thumbnail-sized image:
```
{{< image src="/images/thumb.jpg" alt="Thumbnail" class="w-48 h-48 object-cover rounded-lg" >}}
```

Full-width featured image:
```
{{< image src="/images/feature.jpg" alt="Featured image" class="w-full aspect-video object-cover rounded-xl shadow-xl" >}}
```

Centered half-width with border:
```
{{< image src="/images/centered.jpg" alt="Centered" class="w-1/2 mx-auto rounded-lg border-2 border-accent" >}}
```

Small inline image:
```
{{< image src="/images/small.jpg" alt="Small" class="w-32 h-32 rounded-full object-cover inline-block" >}}
```

## Gallery

Create a responsive image gallery grid with automatic column layout. Gallery content uses markdown image syntax and is automatically styled to create a polished gallery experience.

### Syntax

```
{{< gallery cols="2" >}}
![Image 1 Alt](/images/image1.jpg)
![Image 2 Alt](/images/image2.jpg)
![Image 3 Alt](/images/image3.jpg)
{{< /gallery >}}
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| cols | No | Number of columns (default: 2, responsive on mobile) |

### Example

Three-column gallery:
```
{{< gallery cols="3" >}}
![Mountain View](/images/mountain1.jpg)
![Mountain View](/images/mountain2.jpg)
![Mountain View](/images/mountain3.jpg)
{{< /gallery >}}
```

**Note:** Gallery content should be written in standard markdown image syntax `![alt](url)`. The shortcode automatically applies responsive grid styling, handles image sizing, and ensures accessibility.

## Contact Form

Embed a fully functional contact form with client-side validation, AJAX submission, and multilingual support. The form handles user submissions and displays loading states and error/success messages automatically.

### Syntax

```
{{< contact >}}
```

### Parameters

None - the form is fully self-contained and requires no parameters.

### Example

```markdown
## Get in Touch

Send me a message and I'll respond as soon as possible.

{{< contact >}}
```

### Features

- **Client-side validation**: Required field checking and email format validation
- **Loading state**: Visual feedback during form submission
- **Success/error messages**: Multilingual success and error feedback via i18n
- **Multilingual labels**: All form labels translated for each language
- **AJAX submission**: Non-blocking form submission
- **Accessibility**: ARIA labels, semantic HTML, keyboard navigation

### Backend Implementation

To make the contact form functional, implement backend logic in `static/contact.php`:

#### Expected Request

The form sends POST requests to `/contact.php` with the following data:
```json
{
  "name": "User Name",
  "email": "user@example.com",
  "subject": "Message Subject",
  "message": "Message content"
}
```

#### Successful Response

Return a JSON response with HTTP 200:
```json
{
  "success": true,
  "message": "Thank you for your message. I'll get back to you soon."
}
```

#### Error Response

Return a JSON response with appropriate HTTP status code:
```json
{
  "success": false,
  "error": "An error occurred while sending your message."
}
```

#### Example Implementation (PHP)

```php
<?php
// static/contact.php
header('Content-Type: application/json');
header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: POST');

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
  http_response_code(405);
  echo json_encode(['success' => false, 'error' => 'Method not allowed']);
  exit;
}

$data = json_decode(file_get_contents('php://input'), true);

// Validate input
if (empty($data['name']) || empty($data['email']) || empty($data['message'])) {
  http_response_code(400);
  echo json_encode(['success' => false, 'error' => 'Missing required fields']);
  exit;
}

// Sanitize and validate email
$email = filter_var($data['email'], FILTER_SANITIZE_EMAIL);
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
  http_response_code(400);
  echo json_encode(['success' => false, 'error' => 'Invalid email address']);
  exit;
}

// Send email or save to database
$to = 'contact@danix.xyz';
$subject = htmlspecialchars($data['subject'] ?? 'New Contact Form Submission');
$message = "Name: " . htmlspecialchars($data['name']) . "\n";
$message .= "Email: " . htmlspecialchars($email) . "\n";
$message .= "Message:\n" . htmlspecialchars($data['message']);

if (mail($to, $subject, $message)) {
  echo json_encode(['success' => true, 'message' => 'Message sent successfully']);
} else {
  http_response_code(500);
  echo json_encode(['success' => false, 'error' => 'Failed to send message']);
}
?>
```

## Future Shortcodes

The following shortcodes are planned for future releases:

- **Video**: Privacy-friendly YouTube and Vimeo embeds with custom thumbnail support
- **Callout**: Highlighted information boxes for notes, warnings, and tips
- **Tabs**: Tabbed content sections for organizing related information
- **Code**: Enhanced code blocks with syntax highlighting and line numbers
- **Audio**: Audio player for podcast episodes and sound files

## Accessibility Notes

All shortcodes follow accessibility best practices to achieve WCAG 2.1 AA compliance:

- **Semantic HTML**: Proper heading hierarchy and meaningful elements
- **Alt text**: Images include descriptive alt text for screen readers
- **ARIA labels**: Form fields and interactive elements use ARIA attributes
- **Keyboard navigation**: All interactive elements are keyboard accessible
- **Focus indicators**: Clear visual focus indicators for keyboard users
- **Color contrast**: Text meets minimum contrast ratio requirements
- **Language attributes**: Proper `lang` attributes for multilingual content

## Troubleshooting

### Image not displaying

**Problem:** An image shortcode isn't showing the image.

**Solution:**
- Verify the image path is correct relative to your project root
- Ensure the image file actually exists in the correct location
- Check the browser console for any loading errors
- For Page Bundles, verify the image path starts with `/` (absolute) or uses relative paths correctly

### Gallery not showing columns properly

**Problem:** Gallery images aren't displaying in the specified number of columns.

**Solution:**
- Verify the `cols` parameter is a number (not a string)
- Check that mobile responsive behavior is working as expected
- Ensure markdown image syntax is correct: `![alt text](/path/to/image)`
- Verify no extra whitespace or formatting issues in gallery content

### Contact form not submitting

**Problem:** Form submission fails or shows error messages.

**Solution:**
- Check browser console for JavaScript errors or network issues
- Verify `/contact.php` exists in your `static/` directory
- Ensure the backend implementation is correct and handles POST requests
- Check that your hosting supports PHP and the mail function (or alternative)
- Verify CORS headers are correctly set if using a different domain for the backend

## Contributing

To add new shortcodes to the theme:

1. **Create the shortcode template** in `themes/danix-xyz-hacker/layouts/shortcodes/` directory
2. **Ensure i18n support** by referencing translation strings from `i18n/` files
3. **Add accessibility features** (alt text, ARIA labels, semantic HTML)
4. **Create responsive designs** using Tailwind CSS utilities
5. **Update this documentation** with a new section including syntax, parameters, examples, and features
6. **Reference** the CLAUDE.md guidelines for development standards

For detailed development guidelines, see [CLAUDE.md](./CLAUDE.md).