path: root/SHORTCODES.md

# Shortcodes Documentation - danix.xyz

The danix.xyz theme provides 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 | Conditional | Path or URL to the image file (required unless inner content is provided) |
| alt | No | Alt text for accessibility (default: "Image") |
| caption | No | Optional caption displayed below the image |
| class | No | CSS classes for the `<img>` element (default: "w-full h-auto rounded-lg border border-border"). Overrides all defaults when specified. |
| link | No | URL to wrap the image in a clickable link |
| figure-class | No | CSS classes applied to the outer `<figure>` element (e.g., for centering or custom layout) |

### 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" >}}
```

With link:
```
{{< image src="/images/mountain.jpg" alt="Mountain landscape" link="https://github.com/example" caption="Click to view project" >}}
```

Centered image with figure-class:
```
{{< image src="/images/mountain.jpg" alt="Mountain landscape" caption="Alpine view" figure-class="text-center" >}}
```

### 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.

## Video

Embed responsive HTML5 video player with support for WebM, MP4, and other web video formats. Videos can be stored in page bundles or served from external URLs.

### Syntax

```
{{< video src="video.webm" width="100%" height="600" controls >}}
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| src | Conditional | Path or URL to the video file (required if `id` is not provided; supports .webm, .mp4, .ogv) |
| id | Conditional | YouTube video ID (required if `src` is not provided; triggers YouTube embed mode) |
| title | No | Descriptive title for accessibility (default: "Video"; used as iframe title attribute) |
| width | No | Video width (default: 100%, can be px or % values; video mode only) |
| height | No | Video height (default: auto; video mode only) |
| class | No | Custom CSS classes for styling |
| autoplay | No | Set to "true" to autoplay (default: false; video mode only) |
| loop | No | Set to "true" for looping playback (default: false; video mode only) |
| muted | No | Set to "true" to mute by default (default: false; video mode only) |

### Example

Basic usage with page bundle video:
```
{{< video src="demo.webm" >}}
```

With custom dimensions:
```
{{< video src="tutorial.webm" width="800" height="600" >}}
```

Autoplay and loop:
```
{{< video src="background.webm" width="100%" autoplay="true" loop="true" muted="true" >}}
```

External video URL:
```
{{< video src="https://example.com/video.mp4" width="100%" >}}
```

YouTube embed (recommended for privacy and performance):
```
{{< video id="dQw4w9WgXcQ" title="Example YouTube video" >}}
```

YouTube with custom sizing:
```
{{< video id="dQw4w9WgXcQ" title="Example YouTube video" class="max-w-2xl mx-auto" >}}
```

### Page Bundle Videos

Videos stored in the same directory as your article's `index.md` are automatically resolved:

```
content/en/articles/my-article/
├── index.md
└── demo.webm        ← Reference as src="demo.webm"
```

The template automatically generates the correct URL: `/articles/my-article/demo.webm`

### Browser Compatibility

- **WebM (.webm)**: Chrome, Firefox, Edge
- **MP4 (.mp4)**: All modern browsers (H.264 codec)
- **Ogg Theora (.ogv)**: Firefox, Chrome

## 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']);
}
?>
```

## Quote

Display blockquote with optional attribution. Perfect for testimonials, quotes, and highlighted text.

### Syntax

```
{{< quote source="Author Name" src="https://example.com" >}}
Your quote text here
{{< /quote >}}
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| source | No | Author or source attribution |
| src | No | URL to link the source (requires source parameter) |

### Example

Basic quote:
```
{{< quote source="Maya Angelou" >}}
There is no greater agony than bearing an untold story inside you.
{{< /quote >}}
```

With source link:
```
{{< quote source="Steve Jobs" src="https://en.wikipedia.org/wiki/Steve_Jobs" >}}
The only way to do great work is to love what you do.
{{< /quote >}}
```

## Actions

Display a styled action button, typically used for downloads or calls-to-action.

### Syntax

```
{{< actions url="https://example.com/file.zip" desc="Download File" >}}
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| url | Yes | URL the button links to |
| desc | No | Button label text (default: "Download") |
| outclass | No | CSS classes for the wrapper div |
| inclass | No | CSS classes for the anchor link element |

### Example

Basic download button:
```
{{< actions url="https://github.com/user/project/archive.zip" desc="Download ZIP" >}}
```

With custom styling:
```
{{< actions url="https://example.com/guide.pdf" desc="Download PDF Guide" outclass="my-6" inclass="primary" >}}
```

## Future Shortcodes

The following shortcodes are planned for future releases:

- **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

## Deprecated Shortcodes

The following shortcodes have been consolidated and are no longer available:

| Deprecated | Replacement | Migration |
|-----------|------------|-----------|
| `{{< figure >}}` | `{{< image >}}` | Use `{{< image >}}` with the `figure-class` parameter for styling the figure element |
| `{{< img >}}` | `{{< image >}}` | Directly replace with `{{< image >}}` and add proper `alt` text |
| `{{< gal-img >}}` | Markdown syntax inside `{{< gallery >}}` | Replace `{{< gal-img ... >}}` calls with standard markdown: `![alt](src)` |
| `{{< youtube ID >}}` | `{{< video id="ID" >}}` | Change `{{< youtube ID >}}` to `{{< video id="ID" title="Description" >}}` |

### Why These Changes?

The consolidation reduces maintenance overhead and provides better functionality:
- **`image` shortcode** now supports all image display modes with flexible parameters
- **`video` shortcode** unifies local video and YouTube embeds in one interface
- **`gallery` shortcode** uses standard markdown image syntax for better clarity
- **WCAG AA compliance** improved with required `title` attributes on YouTube iframes

## 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).