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:
Incorrect collection type - Must match your content
Insufficient related content - Need minimum 3-4 items with similar attributes
Category/tag mismatch - Content must have proper categorization
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 typeNo related items
= Insufficient content or poor categorizationAPI 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:
Verify category names exactly match:
javascript
// Check actual category names in console
console.log(document.querySelectorAll('[data-category]'));
Use flexible matching:
javascript
pluginRelatedContent({
'matchBy': 'tags', // More flexible than categories
'minimumMatches': 1, // Lower threshold
'fallbackToAll': true // Show random items if no matches
});
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
});