Simple, Reliable Content Discovery

XenT’s related posts system uses tag and category similarity to recommend relevant content. This approach is:

• Fast: No network requests or external APIs
• Reliable: Works offline and never fails builds
• Transparent: Users understand why posts are related
• Zero-config: Works immediately with your existing tags

How It Works

The system calculates similarity between posts using the Jaccard index:

similarity = |tags_A ∩ tags_B| / |tags_A ∪ tags_B|

For example:

• Post A: ['typescript', 'react', 'hooks']
• Post B: ['react', 'hooks', 'testing']
• Similarity: 2/4 = 0.5 (50% similarity)

Configuration

Enable related posts in your config:

// user.config.ts
export default defineConfig({
  content: {
    relatedPosts: {
      enabled: true,
      maxPosts: 3, // Number of related posts to show
      minSimilarity: 0.1, // Minimum similarity threshold
    },
  },
});

Configuration Options

Option	Default	Description
enabled	true	Enable/disable related posts
maxPosts	3	Maximum number of related posts to display
minSimilarity	0.1	Minimum similarity score (0-1) to show a post

How Posts Are Selected

1. Calculate similarity with current post’s tags and categories
2. Filter by threshold - only posts above minSimilarity
3. Sort by score - highest similarity first
4. Take top N - limited by maxPosts
5. Fallback to recent - if no similar posts found

Best Practices

Tagging Strategy

• Use consistent tags across related posts
• 3-5 tags per post works best
• Mix specific (react-hooks) and general (javascript) tags
• Use categories for broader groupings

Example Tag Structure

// Good tagging for discoverability
{
  title: "Advanced React Hooks",
  tags: ['react', 'hooks', 'javascript', 'frontend'],
  categories: ['Development']
}

{
  title: "Testing React Hooks",
  tags: ['react', 'hooks', 'testing', 'jest'],
  categories: ['Development']
}
// These posts will have 50% similarity (2/4 shared tags)

Implementation Details

The related posts system uses:

• Jaccard similarity for robust tag matching
• Case-insensitive comparison for consistency
• Combined tags and categories for richer matching
• Recent posts fallback when no similar content exists

Performance

• Build time: Negligible impact (milliseconds)
• Runtime: Fast in-memory calculations
• Bundle size: ~1KB additional JavaScript
• Dependencies: Zero external dependencies

Comparison with AI Embeddings

Feature	Tag-Based	AI Embeddings
Setup	Zero config	API keys, providers
Build time	Instant	Minutes (network calls)
Reliability	100%	Depends on API uptime
Cost	Free	API costs per request
Transparency	Clear why posts match	Black box recommendations
Offline	Yes	No

Advanced Usage

Custom Similarity Logic

For special cases, you can extend the related posts utility:

// src/utils/customRelatedPosts.ts
import { getRelatedPosts } from '@/utils/relatedPosts';

export function getRelatedPostsWithBoost(post, allPosts) {
  const related = getRelatedPosts(post, allPosts);

  // Boost posts in same category
  return related.sort((a, b) => {
    const aBoost = a.data.categories?.includes(post.data.categories?.[0]) ? 0.1 : 0;
    const bBoost = b.data.categories?.includes(post.data.categories?.[0]) ? 0.1 : 0;
    return bBoost - aBoost;
  });
}

Tag Cloud Integration

Related posts work naturally with tag clouds:

// Get posts by specific tags
import { getPostsByTags } from '@/utils/relatedPosts';

const reactPosts = getPostsByTags(['react'], allPosts);

Migration from AI Embeddings

If you’re coming from the AI embedding system:

1. No config changes needed - tag-based system uses same settings
2. Performance improvement - builds will be significantly faster
3. No API setup required - remove embedding provider configuration
4. Better transparency - users can see tag relationships

Troubleshooting

No Related Posts Showing

1. Check tags: Ensure posts have overlapping tags
2. Lower threshold: Reduce minSimilarity in config
3. Add more tags: Use 3-5 relevant tags per post
4. Check categories: Categories count as tags for similarity

Too Many/Few Related Posts

• Too many: Increase minSimilarity or reduce maxPosts
• Too few: Decrease minSimilarity or add more tags to posts

The tag-based system provides reliable, fast content discovery that scales with your blog without external dependencies.