SEO optimization

[fretchen]

SEO Optimization: Essential Features for Better Search Visibility

Overview

This issue outlines critical SEO improvements needed to enhance the website's search engine visibility and user engagement. The current implementation lacks essential SEO infrastructure that prevents optimal indexing and discovery.

Current SEO Status

✅ What We're Doing Well

• Clean URLs (no .html extensions)
• Fast loading (Vite optimization)
• Mobile responsive design
• Semantic HTML structure
• Analytics (Umami) already integrated
• Regular publishing with dates
• Rich content (interactive posts, NFTs)

❌ Critical Missing Features

• Meta descriptions for individual pages
• Tags/categories system
• SEO-friendly URL slugs
• Schema.org structured data
• XML sitemap generation
• Related posts functionality

Priority 1: Essential SEO Infrastructure

1. Meta Tags & Open Graph Support

Problem: Poor search result snippets, no social media previews
Impact: Low click-through rates from search results

Implementation:

// Update BlogPost interface
export interface BlogPost {
  title: string;
  content: string;
  description?: string;        // Meta description (150-160 chars)
  keywords?: string[];         // SEO keywords
  tags?: string[];            // Content tags
  category?: string;          // Primary category
  slug?: string;              // URL-friendly slug
  featured_image?: string;    // Social media image
}

Files to modify:

• types/BlogPost.ts
• utils/getBlogs.ts (frontmatter parsing)
• Individual blog pages (meta tag generation)

2. Dynamic Page Titles & Descriptions

Problem: Generic titles, missing descriptions
Current: All pages use default title/description

Implementation:

// Better individual blog page SEO
export function title(pageContext: PageContext) {
  const blog = blogs[id];
  return `${blog.title} | Fred's Blog`;
}

export function description(pageContext: PageContext) {
  const blog = blogs[id];
  return blog.description || extractDescription(blog.content);
}

Files to modify:

• pages/blog/@id/+title.ts
• Create pages/blog/@id/+description.ts
• Add utility function for content description extraction

Priority 2: Content Organization

3. Tags & Categories System

Problem: No topical clustering, poor internal linking
Impact: Missed long-tail keywords, poor content discoverability

Markdown frontmatter example:

---
title: "Can we decentralize access to quantum computing?"
description: "Exploring how smart contracts could democratize quantum computing access through decentralized technologies"
tags: ["quantum-computing", "blockchain", "decentralization", "smart-contracts"]
category: "technology"
publishing_date: 2025-10-02
tokenID: 123
---

Implementation needs:

• Update frontmatter parsing in utils/getBlogs.ts
• Create tag/category listing pages
• Add tag filtering functionality
• Tag-based related posts

4. SEO-Friendly URL Slugs

Problem: Numeric IDs in URLs
Current: /blog/0, /blog/1, /blog/2
Target: /blog/quantum-computing-smart-contracts

Implementation:

function generateSlug(title: string): string {
  return title
    .toLowerCase()
    .replace(/[^a-z0-9\s-]/g, '')
    .replace(/\s+/g, '-')
    .substring(0, 60);
}

Files to modify:

• Update routing in pages/blog/@slug/+Page.tsx
• Update blog listing to use slugs
• Add slug generation to blog processing
• Handle URL redirects for existing numeric URLs

Priority 3: Rich Content Features

5. Schema.org Structured Data

Problem: No structured data for search engines
Impact: Missed rich snippets, poor search result appearance

Implementation:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Can we decentralize access to quantum computing?",
  "author": {"@type": "Person", "name": "Fred Jendrzejewski"},
  "datePublished": "2025-10-02",
  "description": "Exploring how smart contracts...",
  "keywords": ["quantum computing", "blockchain"],
  "url": "https://fretchen.github.io/blog/quantum-computing-smart-contracts"
}
</script>

Files to modify:

• Create structured data component
• Add to individual blog pages
• Include author information
• Add organization schema for homepage

6. XML Sitemap Generation

Problem: No sitemap for search engine crawling
Implementation: Generate dynamic sitemap including all blog posts and pages

Files to create:

• public/sitemap.xml (generated)
• Build script for sitemap generation
• Include in robots.txt

Priority 4: User Engagement

7. Related Posts Functionality

Problem: Poor internal linking
Implementation:

function getRelatedPosts(currentPost: BlogPost): BlogPost[] {
  return blogs.filter(blog => 
    blog.tags?.some(tag => currentPost.tags?.includes(tag))
  ).slice(0, 3);
}

8. Consistent Commenting System

Current: Giscus comments only on some posts
Target: Consistent commenting across all posts with engagement metrics

Implementation Tasks

Task 1: Basic Meta Infrastructure

• Add description field to BlogPost interface
• Update frontmatter parsing for descriptions
• Add content description extraction utility
• Implement dynamic page descriptions

Task 2: Tags System

• Add tags and category fields to BlogPost interface
• Update frontmatter parsing for tags
• Create tag listing functionality
• Add tags display to blog cards

Task 3: URL Slugs

Task 4: Structured Data

• Create Schema.org component for blog posts
• Add structured data to individual pages
• Implement organization schema for homepage
• Test with Google Rich Results Test

Task 5: Sitemap & Navigation

• Generate XML sitemap
• Update robots.txt
• Implement related posts functionality
• Add breadcrumb navigation

Task 6: Optimization & Testing

• Improve internal linking
• Test all SEO implementations
• Validate structured data
• Performance optimization

Success Metrics

SEO Improvements

• All blog posts have unique meta descriptions
• Structured data validates in Google Search Console
• XML sitemap generated and submitted
• URL structure uses descriptive slugs

User Experience

• Related posts increase page views
• Tags enable content discovery
• Consistent commenting across all posts
• Improved social media sharing

Files That Need Changes

Core Infrastructure

• types/BlogPost.ts - Add SEO fields
• utils/getBlogs.ts - Parse new frontmatter fields
• pages/+config.ts - Default SEO configuration

Blog System

• pages/blog/@id/+Page.tsx - Dynamic SEO tags
• pages/blog/@id/+title.ts - Improved titles
• pages/blog/@id/+description.ts - New file for descriptions
• components/EntryList.tsx - Display tags and categories

New Components

• components/SEOHead.tsx - Meta tags component
• components/StructuredData.tsx - Schema.org markup
• components/RelatedPosts.tsx - Related content
• components/TagList.tsx - Tag display and navigation

Technical Notes

Slug Migration Strategy

• Generate slugs for existing posts based on titles
• Maintain backward compatibility with numeric IDs
• Implement 301 redirects from old URLs to new slugs

Content Description Extraction

function extractDescription(content: string, maxLength = 160): string {
  // Remove markdown formatting
  const plainText = content.replace(/[#*`]/g, '').trim();
  // Take first paragraph or first N characters
  const firstParagraph = plainText.split('\n\n')[0];
  return firstParagraph.length > maxLength 
    ? firstParagraph.substring(0, maxLength - 3) + '...'
    : firstParagraph;
}

Tag System Implementation

• Support hierarchical categories (e.g., "technology > quantum-computing")
• Generate tag clouds for popular topics
• Create tag-based RSS feeds
• Implement tag-based search functionality

Expected Impact

Search Engine Optimization

• Meta descriptions: +15-25% CTR improvement
• URL slugs: Better keyword targeting and user trust
• Structured data: Rich snippets and improved SERP appearance
• Tags/categories: Better topical authority and long-tail ranking

User Experience

• Related posts: +20-30% page views per session
• Tag navigation: Improved content discovery
• Better URLs: Increased social sharing and bookmarking

Performance Metrics

• Improved Google PageSpeed Insights SEO score
• Better Core Web Vitals (through optimized meta loading)
• Increased organic search traffic
• Higher engagement metrics (time on site, pages per session)

[fretchen]

I just got the update recommendations

SEO Improvement Recommendations

Status: ✅ Category System Implemented
Next Priority: High-Impact SEO Improvements

---

📊 Impact Assessment

Based on current blog structure (20 posts, 6 categories), the following improvements offer the best ROI:

Improvement	Effort	SEO Impact	User Experience Impact	Priority
Schema.org Markup	30-45 min	🟢🟢 Medium-High	Neutral	HIGH
Internal Linking	1-2 hours	🟢🟢🟢 High	🟢🟢 Good	HIGH
Related Posts Widget	2-3 hours	🟢🟢 Medium	🟢🟢🟢 Excellent	HIGH
Category Archive Pages	3-4 hours	🟡 Low-Medium	🟡 Minimal	LOW
Sitemap.xml	15 min	🟢 Medium	Neutral	MEDIUM

Recommendation: Focus on the top 3 (Schema.org, Internal Linking, Related Posts)

---

🎯 Issue #1: Schema.org BlogPosting Markup

Priority: 🔴 HIGH
Effort: ⏱️ 30-45 minutes
SEO Impact: 🟢🟢 Medium-High (Featured Snippets, Rich Results)

Problem

Blog posts currently lack structured data, missing opportunities for:

• Featured Snippets in Google Search
• Rich results (author, date, reading time)
• Better indexing signals for search engines

Solution

Add BlogPosting schema to individual blog post pages.

Implementation Steps

1. Create Schema.org Helper (15 min)

File: website/utils/schemaOrg.ts (NEW)

import type { BlogPost } from "../types/BlogPost";

export function generateBlogPostingSchema(
  blog: BlogPost,
  url: string,
  imageUrl?: string
) {
  return {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    "headline": blog.title,
    "description": blog.description || "",
    "datePublished": blog.publishing_date,
    "author": {
      "@type": "Person",
      "name": "Frederik Jendrzejewski",
      "url": "https://www.fretchen.eu"
    },
    "publisher": {
      "@type": "Person",
      "name": "Frederik Jendrzejewski",
      "url": "https://www.fretchen.eu"
    },
    "url": url,
    "mainEntityOfPage": {
      "@type": "WebPage",
      "@id": url
    },
    ...(imageUrl && {
      "image": {
        "@type": "ImageObject",
        "url": imageUrl
      }
    })
  };
}

export function generateBreadcrumbSchema(items: Array<{ name: string; url: string }>) {
  return {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": items.map((item, index) => ({
      "@type": "ListItem",
      "position": index + 1,
      "name": item.name,
      "item": item.url
    }))
  };
}

2. Add to Blog Post Head (15 min)

File: website/pages/blog/@id/+Head.tsx

import { generateBlogPostingSchema } from "../../../utils/schemaOrg";

export function Head({ data }) {
  const { blog } = data;
  const url = `https://www.fretchen.eu/blog/${data.id}`;
  
  // Generate NFT image URL if available
  const imageUrl = blog.tokenID 
    ? `https://nft.fretchen.eu/images/${blog.tokenID}.png`
    : undefined;

  const schema = generateBlogPostingSchema(blog, url, imageUrl);

  return (
    <>
      {/* Existing meta tags */}
      
      {/* Schema.org JSON-LD */}
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
      />
    </>
  );
}

3. Test with Rich Results Tool (5 min)

Test your implementation:
https://search.google.com/test/rich-results

Expected Benefits

• ✅ Eligible for Featured Snippets
• ✅ Rich results in Google Search (author, date, image)
• ✅ Better Click-Through Rate (CTR) from search
• ✅ Improved crawling signals

Resources

• Schema.org BlogPosting
• Google Rich Results Test

---

🎯 Issue #2: Internal Linking Between Posts

Priority: 🔴 HIGH
Effort: ⏱️ 1-2 hours
SEO Impact: 🟢🟢🟢 High (15-20% traffic increase)

Problem

Currently, blog posts exist as isolated pages with minimal cross-linking:

• Readers can't discover related content easily
• Google's crawler has limited paths between posts
• Lower "time on site" metrics
• Missed opportunity to distribute PageRank internally

Solution

Implement strategic internal linking using multiple approaches:

Approach A: Manual Inline Links (High Quality, Manual)

Add contextual links within post content where topics naturally connect.

Example in Markdown:

As I described in my [previous post on NFT galleries](./11), 
the ERC-721 Enumerable extension allows...

Recommended links to add:

Post	Should Link To	Context
nft_gallery.md	collect_imagegen.md	"In my next post, I extended this to..."
merkle_ai_batching.tsx	merkle_ai_batching_fundamentals.tsx	"For fundamentals, see..."
prisoners_dilemma_interactive.tsx	tragedy_of_commons_fishing.tsx	"Another game theory example..."
decentral_like.md	nft_blog.md	"I later improved the payment system..."
blog_stack.md	blog_updates.md	"After 6 months, I made updates..."

Implementation: 30 min to add 8-12 strategic links

Approach B: "See Also" Section (Systematic)

Add a standardized "Related Posts" section at the end of each blog post.

File: website/components/SeeAlso.tsx (NEW)

import React from "react";
import { Link } from "./Link";
import { css } from "../styled-system/css";

interface SeeAlsoProps {
  posts: Array<{
    title: string;
    url: string;
    description?: string;
  }>;
}

export const SeeAlso: React.FC<SeeAlsoProps> = ({ posts }) => {
  return (
    <aside
      className={css({
        marginTop: "2xl",
        padding: "lg",
        backgroundColor: "gray.50",
        borderRadius: "md",
        borderLeft: "4px solid",
        borderColor: "gray.300",
      })}
    >
      <h3 className={css({ fontSize: "lg", fontWeight: "semibold", marginBottom: "md" })}>
        Related Posts
      </h3>
      <ul className={css({ listStyle: "none", padding: 0, display: "flex", flexDirection: "column", gap: "sm" })}>
        {posts.map((post, idx) => (
          <li key={idx}>
            <Link href={post.url} className={css({ fontWeight: "medium", color: "blue.600" })}>
              {post.title}
            </Link>
            {post.description && (
              <p className={css({ fontSize: "sm", color: "gray.600", marginTop: "xs" })}>
                {post.description}
              </p>
            )}
          </li>
        ))}
      </ul>
    </aside>
  );
};

Usage in blog posts:

// At the end of merkle_ai_batching.tsx
<SeeAlso posts={[
  {
    title: "Merkle Trees for LLM Batching - The fundamentals",
    url: "/blog/merkle_ai_batching_fundamentals",
    description: "Deep dive into cryptographic fundamentals"
  },
  {
    title: "A decentral support button",
    url: "/blog/decentral_like",
    description: "How I built blockchain payments for content"
  }
]} />

Implementation: 1h to add to 8-10 key posts

Expected Benefits

• ✅ +15-20% organic traffic (proven via internal link studies)
• ✅ Lower bounce rate (users discover more content)
• ✅ Better crawlability (search engines find all posts faster)
• ✅ Distributed PageRank across important posts

Recommended Link Pairs (High Priority)

blockchain + ai posts:
  nft_gallery ←→ collect_imagegen
  merkle_ai_batching ←→ merkle_ai_batching_fundamentals
  nft_blog ←→ decentral_like

economics posts:
  prisoners_dilemma_interactive ←→ tragedy_of_commons_fishing

quantum posts:
  finishing_amo ←→ smart_quantum
  
meta posts:
  blog_stack → blog_updates
  blog_updates → moving_lectures

---

🎯 Issue #3: Related Posts Widget

Priority: 🔴 HIGH
Effort: ⏱️ 2-3 hours
SEO Impact: 🟢🟢 Medium (10% traffic increase)
UX Impact: 🟢🟢🟢 Excellent (user discovery, engagement)

Problem

At the end of a blog post, readers have no clear path to similar content:

• High bounce rate (users leave after one post)
• Missed engagement opportunities
• Manual effort to discover related posts

Solution

Implement an automatic "Related Posts" widget at the bottom of each blog post, using the category system.

Implementation Steps

1. Create RelatedPosts Component (1h)

File: website/components/RelatedPosts.tsx (NEW)

import React from "react";
import { Link } from "./Link";
import { css } from "../styled-system/css";
import type { BlogPost } from "../types/BlogPost";
import { EntryNftImage } from "./EntryNftImage";

interface RelatedPostsProps {
  currentPost: BlogPost;
  allPosts: BlogPost[];
  maxPosts?: number;
}

export const RelatedPosts: React.FC<RelatedPostsProps> = ({ 
  currentPost, 
  allPosts, 
  maxPosts = 3 
}) => {
  // Filter related posts by category match
  const relatedPosts = allPosts
    .filter(post => {
      // Exclude current post
      if (post.componentPath === currentPost.componentPath) return false;
      
      // Match by primary or secondary category
      const matchesPrimary = 
        post.category === currentPost.category || 
        post.category === currentPost.secondaryCategory;
      const matchesSecondary = 
        post.secondaryCategory === currentPost.category ||
        post.secondaryCategory === currentPost.secondaryCategory;
      
      return matchesPrimary || matchesSecondary;
    })
    // Sort by publishing date (newest first)
    .sort((a, b) => {
      if (!a.publishing_date || !b.publishing_date) return 0;
      return new Date(b.publishing_date).getTime() - new Date(a.publishing_date).getTime();
    })
    // Limit number of results
    .slice(0, maxPosts);

  if (relatedPosts.length === 0) return null;

  return (
    <section
      className={css({
        marginTop: "2xl",
        paddingTop: "xl",
        borderTop: "1px solid",
        borderColor: "gray.200",
      })}
    >
      <h2 className={css({ fontSize: "xl", fontWeight: "semibold", marginBottom: "lg" })}>
        Related Posts
      </h2>
      
      <div
        className={css({
          display: "grid",
          gridTemplateColumns: { base: "1fr", md: "repeat(3, 1fr)" },
          gap: "lg",
        })}
      >
        {relatedPosts.map((post, idx) => {
          const postUrl = `/blog/${post.componentPath.split("/").pop()?.replace(/\.(md|mdx|tsx)$/, "")}`;
          
          return (
            <Link
              key={idx}
              href={postUrl}
              className={css({
                display: "flex",
                flexDirection: "column",
                gap: "sm",
                padding: "md",
                borderRadius: "md",
                border: "1px solid",
                borderColor: "gray.200",
                transition: "all 0.2s",
                _hover: {
                  borderColor: "gray.400",
                  backgroundColor: "gray.50",
                },
              })}
            >
              {post.tokenID && (
                <EntryNftImage
                  tokenId={post.tokenID}
                  fallbackImageUrl={post.nftMetadata?.imageUrl}
                  nftName={post.nftMetadata?.name}
                />
              )}
              
              <h3 className={css({ fontSize: "md", fontWeight: "medium", lineHeight: "1.3" })}>
                {post.title}
              </h3>
              
              {post.publishing_date && (
                <time className={css({ fontSize: "sm", color: "gray.600" })}>
                  {post.publishing_date}
                </time>
              )}
              
              {post.description && (
                <p className={css({ fontSize: "sm", color: "gray.700", lineHeight: "1.4" })}>
                  {post.description.slice(0, 100)}...
                </p>
              )}
            </Link>
          );
        })}
      </div>
    </section>
  );
};

2. Integrate into Blog Post Template (30 min)

File: website/pages/blog/@id/+Page.tsx

import { RelatedPosts } from "../../../components/RelatedPosts";
import { loadBlogs } from "../../../utils/blogLoader";

export default function BlogPostPage({ data }) {
  const { blog, allBlogs } = data;
  
  return (
    <article>
      {/* Existing blog post content */}
      
      {/* Add at the end, before footer */}
      <RelatedPosts currentPost={blog} allPosts={allBlogs} maxPosts={3} />
    </article>
  );
}

3. Update +data.ts to Load All Blogs (15 min)

File: website/pages/blog/@id/+data.ts

import { loadBlogs } from "../../../utils/blogLoader";

export const data = async (pageContext) => {
  const { id } = pageContext.routeParams;
  const blogs = await loadBlogs("blog", "publishing_date");
  
  // Load all blogs for related posts
  const allBlogs = blogs;
  
  // Find current blog
  const blog = blogs[parseInt(id)];
  
  return {
    blog,
    allBlogs,
    id,
  };
};

4. Test & Iterate (30 min)

• Test on posts with different categories
• Verify 3 related posts show correctly
• Check mobile responsiveness
• Verify click-through works

Expected Benefits

• ✅ +10% traffic (users discover more posts)
• ✅ 30-40% lower bounce rate
• ✅ Automatic discovery (no manual curation needed)
• ✅ Category system gets utilized for UX
• ✅ More internal links → better SEO

Algorithm Details

Matching Logic:

1. Same primary category → highest priority
2. Primary matches secondary → medium priority
3. Secondary matches secondary → low priority
4. Sorted by date (newest first)
5. Limited to 3 posts

Example:

Current Post: "NFT Gallery" (blockchain + ai)

Related Posts:
1. "Collect ImageGen" (ai + blockchain) - both categories match ✅✅
2. "Merkle AI Batching" (blockchain + ai) - both categories match ✅✅
3. "Decentral Support Button" (blockchain) - primary matches ✅

---

📋 Implementation Checklist

Phase 1: Quick Wins (1-2 hours)

• Implement Schema.org BlogPosting markup
• Test with Rich Results Tool
• Add 8-12 strategic inline links between related posts

Phase 2: Automation (2-3 hours)

• Create RelatedPosts component
• Integrate into blog post template
• Test on multiple posts

Phase 3: Optional (lower priority)

• Generate sitemap.xml (if not already done)
• Add breadcrumb schema
• Consider category archive pages (only if >50 posts)

---

🎯 Success Metrics

Track these after implementation (2-4 weeks):

Metric	Current Baseline	Expected After
Avg. Session Duration	?	+20-30%
Bounce Rate	?	-15-25%
Pages per Session	?	+30-50%
Organic CTR	?	+10-15% (via rich results)
Internal Link Clicks	0	50-100/week

---

📚 Resources

• Schema.org BlogPosting Spec
• Google Search Central - Rich Results
• Moz: Internal Linking Best Practices
• Ahrefs: Internal Linking Study

---

❓ FAQ

Q: Why not implement category archive pages?
A: With only 20 posts and excellent filtering UX, the SEO benefit is minimal (5-10% traffic increase) compared to the effort (3-4 hours). Focus on higher-impact improvements first.

Q: Should I use automatic or manual internal linking?
A: Both! Start with strategic manual links (high quality, contextual), then add automatic Related Posts widget for systematic coverage.

Q: How often should I update internal links?
A: Review every 5-10 new posts. Add links from new posts to relevant older posts.

Q: What about sitemap.xml?
A: If you don't have one, add it (15 min effort, medium impact). Vike/Vite likely has plugins for this.

---

Last Updated: 2025-10-05
Status: Ready for Implementation
Maintainer: @fretchen