Skip to main content

Settings

Color Mode

Theme Skin

Background

Appearance preferences are saved in this browser only.

Environment

Current Environment Production

Built with JEKYLL_ENV=production. Changes require deployment.

Quick Links

Theme & Build

Theme
Jekyll v3.10.0
Last BuildSep 06, 02:35
Repository
bamr87/it-journey
Changelog Docs Jekyll

Page Location

Page Info

Layout quest
Collection quests
Path _quests/0001/seo-optimization.md
URL /quests/0001/seo-optimization/
Date 2025-11-29

Source Code

View on GitHub Edit in GitHub.dev
Configuration
Site Config _config.yml

SEO Optimization: Meta Tags, Sitemaps & Structured Data

Master technical SEO for Jekyll: write meta tags, generate sitemaps and robots.txt, add JSON-LD structured data, and automate it all with jekyll-seo-tag.

Estimated reading time: 27 minutes

Edit on GitHub

Table of Contents

🌱 Lvl 0001Apprentice 🏰 Main Quest 🟢 Easy 45-60 minutes

SEO Optimization: Meta Tags, Sitemaps & Structured Data

Make your Jekyll site discoverable with meta tags, sitemaps, structured data, and jekyll-seo-tag.

Primary Tech
🛠️ jekyll
Skill Focus
Frontend
Series
Jekyll Mastery
Author
IT-Journey Team
XP Range
⚡ 250-500

Your Environment

Showing every platform path

Greetings, brave adventurer! Welcome to SEO Optimization - the quest where you light a beacon so the search engines of the realm can find your work. You can forge the most beautiful site in the kingdom, but if no crawler can read it and no result links to it, it stands silent in the fog. Search Engine Optimization is the craft of making your pages discoverable, understandable, and shareable.

Whether you are publishing a portfolio, a blog, or documentation, this adventure will teach you the technical foundations - titles, descriptions, sitemaps, structured data, and the jekyll-seo-tag plugin - that help your pages rank and appear correctly when shared.

📖 The Legend Behind This Quest

Search engines send out tireless crawlers that read pages, follow links, and build an index of the web. When someone searches, the engine ranks pages from that index. For years people chased tricks, but the durable truth emerged: write good content and make it easy for machines to read. That means a clear <title>, a compelling meta description, a sitemap listing your pages, a robots.txt granting access, and structured data that spells out, in a format machines parse, exactly what a page is about. Get these right and your work surfaces where people are looking.

This quest teaches the technical SEO that static-site authors control, and how Jekyll plugins automate most of it.

🎯 Quest Objectives

By the time you complete this journey, you will have mastered:

Primary Objectives (Required for Quest Completion)

  • Titles & Meta Descriptions - Write the snippets that appear in search results
  • Meta & Open Graph Tags - Control how pages look in search and social shares
  • Sitemaps & robots.txt - Tell crawlers what to read and where to find it
  • Jekyll-seo-tag - Automate metadata generation across a whole site

Secondary Objectives (Bonus Achievements)

  • Structured Data - Add JSON-LD so engines understand your content type
  • Canonical URLs - Prevent duplicate-content confusion
  • Search Console - Verify your site and watch how it is indexed
  • Performance & Accessibility - Audit Core Web Vitals and WCAG basics that lift rank

Mastery Indicators

You’ll know you’ve truly mastered this quest when you can:

  • Write a title and description that earn a click
  • Explain what a sitemap and robots.txt each do
  • Add JSON-LD structured data for an article

🗺️ Quest Prerequisites

📋 Knowledge Requirements

  • Familiarity with HTML and YAML frontmatter
  • Basic command line navigation (cd, ls)
  • Recommended: completion of Advanced Markdown

🛠️ System Requirements

  • Modern operating system (Windows 10+, macOS 10.14+, or Linux)
  • A Jekyll site (or any static site) to edit
  • A text editor or IDE (VS Code recommended)
  • Internet connection for verification tools

🧠 Skill Level Indicators

This 🟢 Easy quest expects:

  • Beginner-friendly - some exposure to Jekyll helps but is not required
  • Willingness to inspect a page’s <head> in DevTools
  • Ready for 45-60 minutes of focused learning

🌍 Choose Your Adventure Platform

SEO lives in your site’s HTML and config. You will edit files and check the output. Pick your setup.

🍎 macOS Kingdom Path

Click to expand macOS instructions 
# In an existing Jekyll site, add the SEO and sitemap plugins
cd ~/my-site
bundle add jekyll-seo-tag jekyll-sitemap
# `bundle add` only edits the Gemfile — Jekyll won't load the plugins until you
# also add them to the `plugins:` list in _config.yml (see Chapter 2). Without
# that step, /sitemap.xml is never generated.
bundle exec jekyll serve

# View the generated metadata
open http://127.0.0.1:4000/

macOS-Specific Notes:

  • Open DevTools (Cmd + Option + I) and inspect the <head> to see generated tags.
  • Visit /sitemap.xml and /robots.txt once the plugins are active.

🪟 Windows Empire Path

Click to expand Windows instructions 
# In an existing Jekyll site, add the SEO and sitemap plugins
cd $HOME\my-site
bundle add jekyll-seo-tag jekyll-sitemap
# `bundle add` only edits the Gemfile — Jekyll won't load the plugins until you
# also add them to the `plugins:` list in _config.yml (see Chapter 2). Without
# that step, /sitemap.xml is never generated.
bundle exec jekyll serve

Start-Process http://127.0.0.1:4000/

Windows-Specific Notes:

  • View source (Ctrl + U) to confirm the <meta> and <title> tags are present.
  • Browse to /sitemap.xml to see every page the crawler will discover.

🐧 Linux Territory Path

Click to expand Linux instructions 
# In an existing Jekyll site, add the SEO and sitemap plugins
cd ~/my-site
bundle add jekyll-seo-tag jekyll-sitemap
# `bundle add` only edits the Gemfile — Jekyll won't load the plugins until you
# also add them to the `plugins:` list in _config.yml (see Chapter 2). Without
# that step, /sitemap.xml is never generated.
bundle exec jekyll serve
xdg-open http://127.0.0.1:4000/

Linux-Specific Notes:

  • curl -s http://127.0.0.1:4000/sitemap.xml | head shows the generated sitemap.
  • curl -s http://127.0.0.1:4000/ | grep -i '<meta' lists your meta tags.

☁️ Cloud Realms Path

Click to expand Cloud/Container instructions 
# No local Jekyll? Edit on GitHub and let GitHub Pages build the site.
# GitHub Pages whitelists jekyll-seo-tag and jekyll-sitemap by default.
# Add them to _config.yml plugins and push; Pages builds with SEO enabled.

Cloud-Specific Notes:

  • Use Google’s Rich Results Test and the Facebook Sharing Debugger on the live URL.
  • GitHub Pages includes both SEO plugins, so no extra build setup is required.

🧙‍♂️ Chapter 1: Titles, Descriptions & Meta Tags - The Search Snippet

The blue link and gray summary you see in search results come straight from your page’s <title> and meta description. These also drive how a link looks when shared on social media.

⚔️ Skills You’ll Forge in This Chapter

  • Writing effective titles and descriptions
  • The essential <head> meta tags
  • Open Graph tags for social sharing

🏗️ The Tags That Matter

A search snippet is built from two tags in your <head>:

<head>
  <!-- The clickable blue headline; aim for ~50-60 characters -->
  <title>SEO for Jekyll Sites: A Practical Beginner Guide</title>

  <!-- The gray summary under it; aim for ~150-160 characters -->
  <meta
    name="description"
    content="Learn the technical SEO every Jekyll author needs: meta tags, sitemaps, structured data, and the jekyll-seo-tag plugin."
  />

  <!-- Tells search engines which URL is the master copy of this page -->
  <link rel="canonical" href="https://example.com/seo-guide/" />
</head>

For social sharing, Open Graph tags control the preview card on platforms like LinkedIn and Slack:

<meta property="og:title" content="SEO for Jekyll Sites" />
<meta property="og:description" content="A practical beginner guide." />
<meta property="og:image" content="https://example.com/preview.png" />
<meta property="og:type" content="article" />

Good titles are specific and front-load the keyword; good descriptions read like a one-sentence pitch, not a keyword stuffing. The description is not a ranking factor by itself, but it heavily influences whether someone clicks.

🔍 Knowledge Check: Titles & Meta

  • What two tags form the snippet shown in search results?
  • What does a canonical URL prevent?
  • Which tags control how a link looks when shared on social media?

⚡ Quick Wins and Checkpoints

  • Wrote a title: A concise, keyword-forward <title> is set
  • Wrote a description: A compelling ~155-character description is set

🧙‍♂️ Chapter 2: Sitemaps, robots.txt & Jekyll-seo-tag - Helping the Crawler

Crawlers need a map and a key. A sitemap lists your URLs; robots.txt grants or restricts access. And jekyll-seo-tag generates most of Chapter 1’s tags for every page automatically.

⚔️ Skills You’ll Forge in This Chapter

  • Generating a sitemap with a plugin
  • Writing a sensible robots.txt
  • Wiring up Jekyll-seo-tag site-wide

🏗️ Automating Metadata

Enable the plugins in _config.yml. These are on GitHub Pages’ allowlist, so they work even without local builds:

# _config.yml
title: My Quest Site
description: A static site forged in the Web Fundamentals tier
url: https://example.com   # full host, no trailing slash
author:
  name: Your Name
  twitter: yourhandle

plugins:
  - jekyll-seo-tag
  - jekyll-sitemap
  - jekyll-feed      # generates /feed.xml so readers and aggregators can subscribe

These three plugins forge your site’s discoverability assets automatically - each is on GitHub Pages’ allowlist:

Plugin Generates Where
jekyll-seo-tag Meta, Open Graph & JSON-LD tags <head> of every page
jekyll-sitemap XML sitemap /sitemap.xml
jekyll-feed RSS feed /feed.xml

Then place a single tag in your layout’s <head>. It reads your _config.yml and each page’s frontmatter and emits the title, description, canonical link, Open Graph, and JSON-LD all at once:

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  {% seo %}
</head>

jekyll-sitemap automatically generates /sitemap.xml - no work beyond adding the plugin. Add a robots.txt at your site root to point crawlers to it:

User-agent: *
Allow: /

Sitemap: https://example.com/sitemap.xml

User-agent: * addresses all crawlers; Allow: / permits the whole site; the Sitemap: line tells them where the map lives.

🔍 Knowledge Check: Sitemaps & Plugins

  • What does the {% seo %} tag generate?
  • What is the purpose of a sitemap versus robots.txt?
  • Why are these two plugins safe to use on GitHub Pages?

⚡ Quick Wins and Checkpoints

  • Sitemap live: /sitemap.xml lists your pages
  • SEO tag working: Page source shows generated meta tags

🧙‍♂️ Chapter 3: Structured Data & Verification - Speaking the Machine’s Language

Beyond plain meta tags, structured data (JSON-LD using schema.org vocabulary) tells engines precisely what a page is - an article, a recipe, a product - which can earn rich results.

⚔️ Skills You’ll Forge in This Chapter

  • Adding JSON-LD structured data
  • Validating it with Google’s tools
  • Verifying ownership in Search Console

🏗️ JSON-LD for an Article

jekyll-seo-tag emits basic JSON-LD for you, but you can add richer data by dropping a script into your page’s head:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "SEO for Jekyll Sites",
  "description": "A practical beginner guide to technical SEO.",
  "author": { "@type": "Person", "name": "Your Name" },
  "datePublished": "2026-06-14",
  "image": "https://example.com/preview.png"
}
</script>

The @type tells the engine this is an Article; the fields map to schema.org’s vocabulary. Search engines can use this to show a richer result with an author, date, and image.

To confirm everything works:

  • Paste the live URL into Google’s Rich Results Test to validate your structured data.
  • Add the site to Google Search Console, verify ownership (a meta tag or DNS record), and submit your sitemap so Google indexes you faster.

🔍 Knowledge Check: Structured Data

  • What format and vocabulary does structured data use here?
  • What does the @type field communicate to a search engine?
  • Which tool validates structured data, and which monitors indexing?

🧙‍♂️ Chapter 4: Performance & Accessibility - Signals That Lift the Rank

Discoverability is only half the beacon. Search engines now weigh how fast a page loads (Core Web Vitals) and how usable it is. A slow or inaccessible page is demoted in results - and turns away the visitors your tags worked to attract. These signals are ranking factors and good craft at once.

⚔️ Skills You’ll Forge in This Chapter

  • Trimming page weight for Core Web Vitals
  • Auditing with Lighthouse
  • Meeting baseline accessibility standards

🏗️ Make Pages Fast

Heavy images are the most common drag on a static site. Resize and compress them before they ship:

# Resize to a sane max width (macOS built-in)
sips --resampleWidth 1200 assets/images/large-photo.jpg

# Or compress in place across a folder with ImageOptim CLI
brew install imageoptim-cli
imageoptim assets/images/

Then tighten the rest of the page:

  • Lazy-load below-the-fold images with loading="lazy"
  • Build for production so Jekyll minifies output: JEKYLL_ENV=production
  • Ship only the JavaScript you need - every extra script blocks render
  • Serve static assets from a CDN when self-hosting
  • Audit with Lighthouse - Chrome DevTools → Lighthouse tab - and chase the score up

🏗️ Make Pages Accessible

Accessible pages rank better, read better in screen readers, and are simply correct. Run this checklist over a page:

  • Every image has descriptive alt text
  • Text meets WCAG AA contrast (4.5:1 ratio)
  • Interactive elements are keyboard-navigable with visible focus
  • Heading hierarchy is logical (h1 → h2 → h3, no skips)
  • Links use descriptive text, never “click here”
  • The page sets a language attribute: <html lang="en">

Verify with a dedicated checker beyond Lighthouse:

Tool Type Where
Lighthouse Browser built-in Chrome DevTools
axe DevTools Browser extension deque.com/axe
WAVE Online checker wave.webaim.org
Pa11y CLI npm install -g pa11y

🔍 Knowledge Check: Performance & Accessibility

  • Which build environment makes Jekyll minify its output?
  • What contrast ratio does WCAG AA require for body text?
  • Name one tool that audits both performance and accessibility.

⚡ Quick Wins and Checkpoints

  • Lighthouse run: You have a baseline score for a key page
  • Alt text pass: Every image on one page has descriptive alt text

🎮 Mastery Challenges

🟢 Novice Challenge: A Perfect Snippet

Objective: Give one page an optimized title and description.

Requirements:

  • A <title> of roughly 50-60 characters
  • A meta description of roughly 150-160 characters
  • A canonical URL

Validation: View source and confirm all three tags render correctly.

🟡 Intermediate Challenge: Crawlable Site

Objective: Make a whole site crawlable and self-describing.

Requirements:

  • Enable jekyll-seo-tag and jekyll-sitemap
  • Add the {% seo %} tag to your layout
  • Add a robots.txt pointing at your sitemap

Validation: /sitemap.xml and /robots.txt both load and the head shows generated tags.

🔴 Advanced Challenge: Rich Results

Objective: Add and validate structured data.

Requirements:

  • Add JSON-LD Article data to a page
  • Validate it with Google’s Rich Results Test
  • Verify the site in Search Console and submit the sitemap

Validation: The Rich Results Test reports no errors for your structured data.

🟡 Bonus Challenge: Audit Speed & Access

Objective: Prove a page is fast and accessible.

Requirements:

  • Run Lighthouse on a key page and record the Performance and Accessibility scores
  • Add alt text to every image and loading="lazy" below the fold
  • Fix the highest-impact issue Lighthouse or axe DevTools reports

Validation: A re-run of Lighthouse shows the score improve after your fix.

🏆 Quest Rewards & Achievements

🎖️ Badges Earned:

  • 🏆 Beacon Keeper - You made a site search engines can find and understand
  • 🌱 Sprout of Discoverability - Meta tags and structured data are second nature

🛠️ Skills Unlocked:

  • Technical SEO for Static Sites - Titles, sitemaps, and crawl control
  • Structured Data & Metadata - Help machines understand your content

🔓 Unlocked Quests:

  • Analytics Integration - Measure the traffic your SEO earns
  • Jekyll Plugins - Automate more of your site’s metadata

📊 Progression Points: +50 XP

🗺️ Next Steps in Your Journey

Continue the Main Story:

Explore Side Adventures:

Character Class Recommendations

💻 Software Developer: Continue to Jekyll Plugins
🏗️ System Engineer: Explore Analytics Integration
🎨 Frontend Specialist: Advance to Analytics Integration

📚 Resources

Official Documentation

Community Resources

Learning Materials

Performance & Accessibility

🤝 Quest Completion Checklist

  • ✅ Completed all primary objectives
  • ✅ Optimized a page’s title, description, and structured data
  • ✅ Answered all knowledge check questions
  • ✅ Completed at least one mastery challenge
  • ✅ Explored the resource library
  • ✅ Identified your next quest in the journey

🕸️ Knowledge Graph

Structured wiki-links connect this quest to the IT-Journey knowledge graph. Open the Obsidian Graph View to explore connections.

Level hub: [[Level 0001 - Web Fundamentals]] Overworld: [[🏰 Overworld - Master Quest Map]] Unlocks: [[Analytics Integration]] · [[Jekyll Plugins]] Obsidian docs: [[Obsidian Knowledge Graph and Wiki Links]]

🎁 Rewards

50 XP

Badges

  • 🏆 Beacon Keeper - Made a site search engines can find and understand
  • 🌱 Sprout of Discoverability - Internalized meta tags and structured data

Skills unlocked

  • 🛠️ Technical SEO for Static Sites
  • 🧠 Structured Data & Metadata

Features unlocked

  • Access to the measurement quests of Level 0001 Web Fundamentals

Unlocks

🕸️ Quest Network

Loading quest graph…

Click a node to open the quest · ⌘/Ctrl-click for a new tab · drag to reposition · scroll to zoom.

Referenced by
  • Loading…