Create and display Instagram-style stories on your WordPress site with an intuitive admin interface, optimized frontend, and gesture navigation.

Ghost Stories brings the "Stories" format to WordPress. Create engaging, ephemeral, and navigable content with a modern modal viewer. Ideal for news sites, blogs, e-commerce, and any website that wants to share stories in an impactful way.

• Instagram-style Stories: Modal viewer with touch navigation
• Media Management: Upload images and videos with drag-and-drop reordering
• Expiration System: Stories that automatically disappear
• Gutenberg Block: Insert stories on any page or post
• REST API: Endpoints for headless integrations
• Responsive: Desktop, tablet, and mobile
• Touch Gestures: Horizontal swipe (media) and vertical swipe (stories)
• Keyboard Navigation: Arrow keys and ESC on desktop
• Performance Optimization: Conditional loading, lazy load, and caching
• Accessibility: ARIA labels and accessible focus
• Title and Subtitle: Dedicated fields displayed under each circle
• Video Controls: Play/Pause, volume, synchronized progress bar

1. Download the plugin ZIP file
2. Go to Plugins → Add New in your WordPress admin
3. Click Upload Plugin and choose the ZIP file
4. Click Install Now
5. After installation, click Activate Plugin

1. Upload the wp-stories-plugin folder to /wp-content/plugins/
2. Activate the plugin through the Plugins menu in WordPress

• WordPress 5.0 or higher
• PHP 7.4 or higher
• PHP extensions: json, mbstring, gd

1. Go to Stories → Add New Story in your WordPress admin
2. Enter a story title
3. Click Add Media to upload images or videos
4. Drag and drop to reorder media items
5. Set expiration time (optional)
6. Click Publish

1. Edit any page or post
2. Add the Stories block
3. Select which stories to display
4. Choose alignment (left, center, right)
5. Publish your page

[wp_stories]

Display specific stories:

[wp_stories ids="1,2,3"]

<?php
if (function_exists('wp_stories_display')) {
    wp_stories_display();
}
?>

Display specific stories:

<?php
if (function_exists('wp_stories_display')) {
    wp_stories_display(array(
        'story_ids' => array(1, 2, 3),
        'alignment' => 'center'
    ));
}
?>

Defines how many hours a story remains visible. When it expires, it is automatically hidden.

• Leave empty for no expiration
• Recommended range: 1–168 hours (1 hour to 7 days)
• Default: 24 hours

• Add Media: Upload new images/videos or select from media library
• Reorder: Drag and drop to change media order
• Remove: Click remove button to delete media from story
• Edit: Click edit to modify media details

Select multiple stories and:

• Extend Expiration: Add 24 hours to expiration time
• Remove Expiration: Make stories permanent

The plugin provides a REST API for accessing stories programmatically.

GET /wp-json/wp-stories/v1/stories

Parameters:

• per_page (int): Stories per page (default: 10, max: 100)
• page (int): Page number (default: 1)
• include_expired (bool): Include expired stories (default: false)
• orderby (string): Sort by date, title, or expiration (default: date)
• order (string): asc or desc (default: desc)

GET /wp-json/wp-stories/v1/stories/{id}

POST /wp-json/wp-stories/v1/stories/{id}/view

Requires nonce for CSRF protection.

// Fetch active stories
fetch('/wp-json/wp-stories/v1/stories')
    .then(response => response.json())
    .then(data => {
        console.log(data.stories);
    });

// Get specific story
fetch('/wp-json/wp-stories/v1/stories/123')
    .then(response => response.json())
    .then(story => {
        console.log(story.title);
        console.log(story.media_items);
    });

wp-stories-plugin/
├── assets/
│   ├── css/
│   │   ├── admin.css          # Admin interface styles
│   │   └── frontend.css       # Frontend modal styles
│   ├── images/
│   │   └── video-placeholder.svg
│   └── js/
│       ├── admin.js           # Admin functionality
│       └── frontend.js        # Frontend modal viewer
├── blocks/
│   └── stories-block/
│       ├── block.json         # Block configuration
│       ├── edit.js            # Block editor component
│       ├── editor.css         # Block editor styles
│       ├── index.js           # Block registration
│       ├── save.js            # Block save function
│       └── style.css          # Block frontend styles
├── includes/
│   ├── class-story-admin.php       # Admin interface
│   ├── class-story-api.php         # REST API endpoints
│   ├── class-story-collection.php  # Story collection management
│   ├── class-story-frontend.php    # Frontend display
│   ├── class-story-media-item.php  # Media item model
│   ├── class-story-post-type.php   # Custom post type
│   ├── class-wp-stories-plugin.php # Main plugin class
│   └── class-wp-story.php          # Story model
├── templates/
│   └── story-modal.php        # Modal template
├── readme.txt                 # WordPress.org readme
├── uninstall.php             # Cleanup on uninstall
└── wp-stories-plugin.php     # Main plugin file

// Fired when plugin is initialized
do_action('wp_stories_plugin_init');

// Fired when a story is viewed
do_action('wp_stories_story_viewed', $story_id);

// Fired when a story expires
do_action('wp_stories_story_expired', $story_id);

// Modify default expiration hours
add_filter('wp_stories_default_expiration', function($hours) {
    return 48; // 48 hours instead of 24
});

// Modify maximum media items per story
add_filter('wp_stories_max_media_items', function($max) {
    return 20; // 20 items instead of 10
});

// Modify allowed media types
add_filter('wp_stories_allowed_media_types', function($types) {
    return array('image/jpeg', 'image/png', 'video/mp4');
});

• Click left/right: Navigate between media items
• Arrow keys: Navigate between media items
• ESC key: Close modal
• Click X: Close modal

• Swipe left/right: Navigate between media items
• Tap left/right: Navigate between media items
• Tap X: Close modal
• Swipe down: Close modal

• Progress bars show current position in story
• Auto-advance after 5 seconds per media item
• Hold/touch to pause auto-advance

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile Safari (iOS 12+)
• Chrome Mobile (Android 8+)

The plugin is optimized for performance:

• Conditional Loading: Assets only load when stories are present
• Lazy Loading: Images load as needed
• Caching: Story data is cached for faster retrieval
• Optimized Queries: Efficient database queries
• Minification Ready: Assets can be minified for production

Security features include:

• Nonce Verification: All AJAX requests verified
• Capability Checks: User permissions validated
• Input Sanitization: All user input sanitized
• Output Escaping: All output properly escaped
• CSRF Protection: Cross-site request forgery prevention
• SQL Injection Prevention: Prepared statements used
• File Upload Validation: Media files validated before upload

1. Check that stories are published (not draft)
2. Verify stories haven't expired
3. Clear WordPress cache
4. Check browser console for JavaScript errors

1. Check PHP upload_max_filesize setting
2. Verify file permissions on wp-content/uploads
3. Check allowed file types in WordPress settings
4. Review PHP error log for upload errors

1. Check for JavaScript conflicts with other plugins
2. Verify jQuery is loaded
3. Check browser console for errors
4. Try disabling other plugins temporarily

1. Enable WordPress caching plugin
2. Optimize images before upload
3. Limit number of media items per story
4. Use CDN for media files

• Initial release
• Instagram-style story viewer
• Admin interface for story management
• Gutenberg block integration
• REST API endpoints
• Expiration system
• Touch gesture support
• Keyboard navigation
• Responsive design

For support, please:

1. Check the documentation above
2. Review troubleshooting section
3. Check WordPress.org support forums
4. Submit issues on GitHub (if applicable)

Developed with ❤️ for the WordPress community.

This plugin is licensed under the GPL v2 or later.

Copyright (C) 2024

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

This plugin:

• Does not collect any user data
• Does not send data to external servers
• Does not use cookies for tracking
• Stores story view counts locally (optional)
• All data remains on your WordPress installation

For a complete guide with screenshots, best practices, customization, troubleshooting, and frequently asked questions, see: USER_GUIDE.md.

• Displayed one below the other under each circle.
• Title from meta _story_title (fallback to post_title if not present).
• Subtitle from meta _story_detail (optional).
• Default typography: "Playwrite Australia Tasmania" (Google Fonts).
• Truncated with ellipsis and maximum width designed for the circle layout.