Related Posts and Products Plugin FAQs

Installation & Configuration Issues

Q: Why does my related posts/products section just show a spinning wheel? A: Loading issues troubleshooting:

Common causes:

1. Incorrect collection type - Must match your content

2. Insufficient related content - Need minimum 3-4 items with similar attributes

3. Category/tag mismatch - Content must have proper categorization

4. Plugin configuration errors - Check syntax and parameters

Step-by-step debugging:

javascript

// Basic configuration check
pluginRelatedContent({
    'collectionType': 'posts', // or 'products'
    'postsLimit': 6,
    'filterByCategoryOnly': true,
    'debug': true // Enable debug mode
});

Check browser console for errors:

• Collection not found = Wrong collection type

• No related items = Insufficient content or poor categorization

• API error = Network or permission issues

Q: Why do related products work for some categories but not others? A: Category-specific issues:

Possible causes:

• Inconsistent category naming - Case sensitivity matters

• Empty categories - Not enough products to find relationships

• New categories - Recently added without sufficient content

• Category hierarchy - Subcategories not being recognized

Solutions:

1. Verify category names exactly match:

javascript

// Check actual category names in console
console.log(document.querySelectorAll('[data-category]'));

1. Use flexible matching:

javascript

pluginRelatedContent({
    'matchBy': 'tags', // More flexible than categories
    'minimumMatches': 1, // Lower threshold
    'fallbackToAll': true // Show random items if no matches
});

1. Debug specific categories:

javascript

pluginRelatedContent({
    'debug': true,
    'logMatching': true, // See what's being matched
    'testCategory': 'Your Category Name'
});

Content Matching & Algorithm

Q: How does the plugin determine which posts/products are "related"? A: Matching algorithm options:

1. Category-based matching (default):

javascript

pluginRelatedContent({
    'matchBy': 'category',
    'exactMatch': true, // Must be same category
    'minimumMatches': 1
});

2. Tag-based matching (more flexible):

javascript

pluginRelatedContent({
    'matchBy': 'tags',
    'minimumSharedTags': 2, // At least 2 shared tags
    'tagWeight': 'equal' // All tags weighted equally
});

3. Hybrid matching:

javascript

pluginRelatedContent({
    'matchBy': 'both', // Categories AND tags
    'prioritize': 'category', // Category matches first
    'fallbackToTags': true // Then tag matches
});

4. Custom attribute matching:

javascript

pluginRelatedContent({
    'matchBy': 'custom',
    'customAttributes': ['color', 'style', 'brand'],
    'attributeWeights': {
        'category': 3,
        'color': 2,
        'style': 1
    }
});

Q: How many related items should I display? A: Optimal display recommendations:

Based on layout:

• Grid layout (3 columns): 3, 6, or 9 items

• List layout: 4-5 items

• Carousel: 5-8 items

• Mobile: 3-4 items maximum

Configuration examples:

javascript

// Responsive item counts
pluginRelatedContent({
    'postsLimit': 6, // Desktop
    'mobilelimit': 3, // Mobile override
    'tabletLimit': 4 // Tablet override
});

// Or use CSS to hide extras on mobile
pluginRelatedContent({
    'postsLimit': 6
});

css

@media screen and (max-width: 767px) {
    .related-items .related-item:nth-child(n+4) {
        display: none; /* Hide items 4+ on mobile */
    }
}

Display Customization & Layout

Q: How do I change the layout of related posts (grid vs list)? A: Layout configuration options:

Grid layout:

javascript

pluginRelatedContent({
    'design': 'grid',
    'columnWidth': '33%', // 3 columns
    'gutter': 20,
    'responsive': true
});

css

.related-posts {
    display: grid !important;
    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)) !important;
    gap: 20px !important;
    margin: 30px 0 !important;
}

.related-item {
    background: white;
    border-radius: 8px;
    overflow: hidden;
    box-shadow: 0 2px 10px rgba(0,0,0,0.1);
    transition: transform 0.3s ease;
}

.related-item:hover {
    transform: translateY(-5px);
}

List layout:

javascript

pluginRelatedContent({
    'design': 'list',
    'orientation': 'horizontal',
    'showExcerpt': true
});

css

.related-posts {
    display: flex !important;
    flex-direction: column !important;
    gap: 15px !important;
}

.related-item {
    display: flex !important;
    align-items: center !important;
    padding: 15px !important;
    border: 1px solid #eee !important;
    border-radius: 5px !important;
}

.related-item-image {
    flex: 0 0 80px !important;
    margin-right: 15px !important;
}

.related-item-content {
    flex: 1 !important;
}

Carousel layout:

javascript

pluginRelatedContent({
    'design': 'carousel',
    'autoScroll': true,
    'scrollSpeed': 3000,
    'showDots': true,
    'showArrows': true
});

Q: Can I show related products on blog posts and vice versa? A: Cross-content relationships:

Enable mixed content:

javascript

pluginRelatedContent({
    'showProductsOnPosts': true,
    'showPostsOnProducts': true,
    'mixedContent': true,
    'mixRatio': '50/50' // Equal mix of posts and products
});

Advanced cross-content matching:

javascript

pluginRelatedContent({
    'crossContentRules': {
        'posts': {
            'showProducts': true,
            'matchBy': 'tags',
            'limit': 3
        },
        'products': {
            'showPosts': true,
            'matchBy': 'category',
            'limit': 2
        }
    }
});

Content type detection:

javascript

// Automatic content type detection
pluginRelatedContent({
    'autoDetectContent': true,
    'primaryContent': 'auto', // Match page type
    'secondaryContent': 'complement' // Show opposite type
});

Styling & Appearance

Q: How do I customize the appearance of related post thumbnails? A: Complete thumbnail styling:

Basic thumbnail styles:

css

.related-post-thumbnail {
    width: 100% !important;
    height: 200px !important;
    object-fit: cover !important;
    border-radius: 8px !important;
    transition: transform 0.3s ease !important;
}

.related-post-thumbnail:hover {
    transform: scale(1.05) !important;
}

/* Aspect ratio containers for consistent sizing */
.related-item-image {
    position: relative;
    width: 100%;
    padding-bottom: 60%; /* 16:10 aspect ratio */
    overflow: hidden;
    border-radius: 8px;
}

.related-post-thumbnail {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    object-fit: cover;
}

Text styling:

css

.related-post-title {
    font-size: 16px !important;
    font-weight: 600 !important;
    margin: 15px 0 8px 0 !important;
    line-height: 1.4 !important;
    color: #333 !important;
}

.related-post-title a {
    text-decoration: none !important;
    color: inherit !important;
    transition: color 0.3s ease !important;
}

.related-post-title a:hover {
    color: #007cba !important;
}

.related-post-excerpt {
    font-size: 14px !important;
    color: #666 !important;
    line-height: 1.5 !important;
    margin-bottom: 10px !important;
}

.related-post-meta {
    font-size: 12px !important;
    color: #999 !important;
    margin-top: 10px !important;
}

Advanced styling with categories:

css

/* Style by category */
.related-item[data-category="technology"] {
    border-left: 4px solid #blue;
}

.related-item[data-category="design"] {
    border-left: 4px solid #green;
}

.related-item[data-category="business"] {
    border-left: 4px solid #orange;
}

/* Category badges */
.related-item-category {
    display: inline-block;
    background: #f0f0f0;
    color: #666;
    padding: 4px 8px;
    border-radius: 12px;
    font-size: 11px;
    text-transform: uppercase;
    letter-spacing: 0.5px;
    margin-bottom: 8px;
}

Positioning & Integration

Q: The related posts section appears in the wrong location. How do I move it? A: Position control methods:

Method 1: Plugin configuration

javascript

pluginRelatedContent({
    'insertAfter': '.blog-item-content', // CSS selector
    'position': 'bottom', // 'top', 'bottom', 'custom'
    'customSelector': '#custom-location'
});

Method 2: CSS positioning

css

.related-posts-container {
    order: 2; /* Control flex order */
    margin: 40px 0 !important;
}

/* Move to sidebar */
.related-posts-sidebar {
    position: absolute;
    right: -300px;
    top: 0;
    width: 250px;
}

Method 3: Manual placement

html

<!-- Add this HTML where you want related content -->
<div id="related-content-location"></div>

<script>
pluginRelatedContent({
    'manualPlacement': true,
    'targetElement': '#related-content-location'
});
</script>

Q: How do I integrate related content with existing page layouts? A: Layout integration strategies:

Sidebar integration:

css

@media screen and (min-width: 1024px) {
    .blog-post-wrapper {
        display: grid;
        grid-template-columns: 1fr 300px;
        gap: 40px;
    }
    
    .related-posts {
        grid-column: 2;
        position: sticky;
        top: 20px;
        height: fit-content;
    }
}

Footer integration:

css

.related-posts {
    background: #f9f9f9;
    padding: 40px 20px;
    margin-top: 60px;
    border-top: 1px solid #eee;
}

.related-posts h3 {
    text-align: center;
    margin-bottom: 30px;
    font-size: 24px;
}

Inline integration:

javascript

pluginRelatedContent({
    'insertAfter': '.blog-item-content p:nth-of-type(3)', // After 3rd paragraph
    'wrapperClass': 'inline-related-content',
    'inlineStyle': true
});

Performance & Optimization

Q: Related content loads slowly or impacts page performance. How do I optimize? A: Performance optimization techniques:

1. Lazy loading:

javascript

pluginRelatedContent({
    'lazyLoad': true,
    'loadOnScroll': true,
    'scrollOffset': 200, // Load when 200px from viewport
    'showPlaceholder': true
});

2. Caching:

javascript

pluginRelatedContent({
    'enableCache': true,
    'cacheExpiry': 3600, // 1 hour cache
    'cacheBusting': false
});

3. Limit API calls:

javascript

pluginRelatedContent({
    'batchRequests': true,
    'maxAPIcalls': 5,
    'requestDelay': 100 // Delay between requests
});

4. Optimize images:

css

.related-post-thumbnail {
    loading: lazy;
    decoding: async;
}

5. Reduce content:

javascript

pluginRelatedContent({
    'showExcerpt': false, // Disable excerpts for faster loading
    'excerptLength': 50, // Shorter excerpts
    'loadImages': 'ondemand' // Load images only when needed
});