From: Danilo M. Date: Wed, 15 Apr 2026 13:54:18 +0000 (+0200) Subject: docs: create comprehensive shortcodes documentation X-Git-Tag: release_22042026-1342~258 X-Git-Url: https://git.danix.xyz/?a=commitdiff_plain;h=f3b755994e28c4481c1306567be7554f42066563;p=danix.xyz-2.git docs: create comprehensive shortcodes documentation --- diff --git a/SHORTCODES.md b/SHORTCODES.md new file mode 100644 index 0000000..d2b7cbe --- /dev/null +++ b/SHORTCODES.md @@ -0,0 +1,283 @@ +# 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: "rounded-lg border border-border/30") | + +### 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" >}} +``` + +## 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_form >}} +``` + +### 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_form >}} +``` + +### 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 + 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/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).