SEO System for rshankar.com

Quick Start Guide for improving SEO across your Jekyll blog.

📚 What’s Been Implemented

Your blog now has a complete SEO infrastructure:

  1. ✅ Automatic meta tags (canonical, Open Graph, Twitter Cards)
  2. ✅ Structured data (JSON-LD for rich snippets)
  3. ✅ Smart fallbacks (uses excerpt when description missing)
  4. ✅ Documentation (guidelines, templates, checklists)
  5. ✅ Audit tools (script to track progress)

🚀 Quick Start (15 Minutes)

1. Check Current Status

./scripts/seo-audit.sh

This shows you exactly what needs work.

2. Update Your First Post

Pick any recent post and add these three lines:

---
title: "Existing Title"
date: "2025-11-01"
description: "Write 120-155 characters describing what readers will learn from this post."
image: "/assets/images/post-slug/featured.png"
permalink: "/descriptive-post-slug/"
---

That’s it! The infrastructure handles the rest.

3. Test It

  1. Build your site locally or push to GitHub
  2. View the page source
  3. Look for <meta name="description"...>
  4. Check for <script type="application/ld+json"> (structured data)

📖 Documentation Guide

For New Posts

👉 Use: _templates/new-post-template.md

For Updating Old Posts

👉 Use: QUICK-SEO-FIX.md

For Complete Reference

👉 Use: SEO-GUIDELINES.md

To Track Progress

👉 Run: ./scripts/seo-audit.sh

For Overview

👉 Read: SEO-IMPLEMENTATION-SUMMARY.md

🎯 Recommended Workflow

Week 1: Foundation

Week 2-4: Bulk Updates

Month 2+: Ongoing Optimization

📊 Current Status

As of 2025-11-01:

Element Coverage Priority
Meta Descriptions 3% (15/429) 🔴 HIGH
Featured Images 1% (8/429) 🟡 MEDIUM
Permalinks 0% (4/429) 🟡 MEDIUM
Categories 98% (423/429) ✅ GOOD
Tags 81% (350/429) ✅ GOOD

Overall SEO Score: 31%

Recent posts (2024-2025) are better: 26% have descriptions!

🛠️ Files Reference

rshankras.github.io/
├── _includes/
│   ├── head/custom.html          ← SEO meta tags (auto)
│   └── structured-data.html      ← JSON-LD schema (auto)
│
├── _templates/
│   └── new-post-template.md      ← Use for new posts
│
├── scripts/
│   └── seo-audit.sh              ← Run to check status
│
├── SEO-README.md                 ← This file (start here)
├── SEO-GUIDELINES.md             ← Complete reference
├── QUICK-SEO-FIX.md              ← Fast update guide
└── SEO-IMPLEMENTATION-SUMMARY.md ← What was done

💡 Pro Tips

Fastest Impact

Focus on recent posts first (2024-2025):

Minimum Viable SEO

For maximum efficiency, just add:

  1. Meta description (5 min)
  2. Featured image path (2 min)

That’s 7 minutes per post for 80% of the benefit!

Default Image Strategy

Don’t have time for custom images?

  1. Create ONE default template image
  2. Use for all posts initially
  3. Replace with custom later

🔧 Common Tasks

Create a New Post

# Copy template
cp _templates/new-post-template.md _posts/2025-11-01-my-new-post.md

# Edit with your favorite editor
code _posts/2025-11-01-my-new-post.md

# Fill in all SEO fields
# Write content
# Check off the checklist at bottom

Update an Old Post

# Open the post
code _posts/2014-01-01-old-post.md

# Add these lines to front matter:
description: "120-155 character description here"
image: "/assets/images/default-featured.png"
permalink: "/descriptive-slug/"

# Save and commit

Check Your Progress

# Run audit
./scripts/seo-audit.sh

# Compare to previous run
./scripts/seo-audit.sh > status-$(date +%Y%m%d).txt

# Review improvement over time
diff status-20251101.txt status-20251201.txt

Find Posts to Update

# Posts missing descriptions
grep -L "description:" _posts/*.md | head -10

# Recent posts missing descriptions
grep -L "description:" _posts/2024-*.md _posts/2025-*.md

# High priority (recent + missing desc)
ls -t _posts/2024-*.md _posts/2025-*.md | head -20 | xargs grep -L "description:"

📈 Measuring Success

Tools to Set Up

  1. Google Search Console (if not already)
    • Monitor impressions
    • Track click-through rates
    • Check for errors
  2. Google Analytics (✅ already installed)
    • Organic traffic
    • Bounce rate
    • Time on page
  3. Social Validators

What to Track Weekly

Expected Results

Month 1:

Month 3:

Month 6:

🤔 FAQ

Q: Do I need to update all 429 posts? A: No! Start with recent posts (2024-2025). That’s only 57 posts and will give you 80% of the benefit.

Q: How long does each post take? A:

Q: What if I don’t have time for custom images? A: Use a default image for now. The description and structured data are more important. Add custom images later.

Q: Will this break my existing posts? A: No! The new system has smart fallbacks. Posts without descriptions will use excerpts automatically.

Q: How do I test if it’s working? A:

  1. View page source (right-click → View Source)
  2. Search for <meta name="description"
  3. Search for application/ld+json
  4. Use Twitter/LinkedIn validators

Q: What’s the minimum I need to do? A: Just add a description: field to your posts. Everything else has automatic fallbacks.

🎓 Learn More

Essential Reading

  1. Start: SEO-README.md (this file)
  2. Update posts: QUICK-SEO-FIX.md
  3. New posts: _templates/new-post-template.md
  4. Reference: SEO-GUIDELINES.md

External Resources

🚨 Troubleshooting

Audit script won’t run:

chmod +x scripts/seo-audit.sh
./scripts/seo-audit.sh

Changes not showing up:

# Clear Jekyll cache
bundle exec jekyll clean
bundle exec jekyll build

# Or just rebuild
bundle exec jekyll serve

Meta tags not appearing:

Structured data errors:

✅ Quick Wins Checklist

Do these today for immediate impact:

Time required: ~1 hour Impact: Noticeable improvement in social sharing

🎉 You’re Ready!

You now have:

Next step: Run the audit and update your first 10 posts!

./scripts/seo-audit.sh

Good luck! 🚀

Questions or issues? Review the detailed guides or check Jekyll documentation.

Made improvements? Update this documentation for your future self!