🔍 IT-Journey SEO Best Practices Guide

Goal: Ensure all IT-Journey content is discoverable, clickable, and valuable to searchers.

---

📋 Table of Contents

1. Core SEO Principles
2. Frontmatter Optimization
3. Content Structure
4. Technical SEO
5. Monitoring & Iteration
6. Quick Reference Checklist

---

🎯 Core SEO Principles

The SEO Mindset

Think like your audience: - What problem are they trying to solve? - What words would they type into Google? - What would make them click YOUR result? - What would make them stay and learn?

The Three Pillars

Pillar	Goal	How We Achieve It
Relevance	Match search intent	Keywords in title, description, content
Authority	Be the best resource	Comprehensive, accurate, well-structured
Experience	Keep users engaged	Fast load, easy navigation, clear value

---

📝 Frontmatter Optimization

Title Best Practices

Formula: [Action/Topic] + [Specifics] + [Context/Benefit]

# ❌ Bad Examples
title: "Docker"
title: "How to use Docker"
title: "My Docker Tutorial"

# ✅ Good Examples
title: "Docker for Beginners: Complete Container Tutorial"
title: "Install Docker on macOS: Step-by-Step Guide"
title: "Docker Compose Tutorial: Multi-Container Applications"

Rules: - 60 characters max (Google truncates longer titles) - Primary keyword near the beginning - Action-oriented when possible - Unique for every page

Description Best Practices

Formula: [What you'll learn] + [How] + [Key benefit]. [Secondary detail].

# ❌ Bad Examples
description: null
description: "A tutorial about Docker"
description: "Learn Docker containerization basics in this comprehensive guide"  # Too vague

# ✅ Good Examples
description: "Step-by-step Docker tutorial for beginners. Learn containers, images, and Docker Compose with hands-on examples. Complete setup guide for macOS, Linux & Windows."

Rules: - 150-160 characters (Google truncates at ~160) - Include primary keyword naturally - Mention platforms when relevant - State clear benefit to the reader - Never leave as null

Tags Strategy

Tag Categories: 1. Topic tags: docker, python, terminal 2. Platform tags: macos, linux, windows 3. Type tags: tutorial, reference, troubleshooting 4. Level tags: beginner, intermediate, advanced 5. Tool tags: vscode, git, npm

# ❌ Too few/generic
tags:
  - article

# ✅ Comprehensive
tags:
  - docker
  - containers
  - tutorial
  - macos
  - linux
  - devops
  - beginner

Rules: - 5-10 tags per post - Mix broad and specific terms - Include platforms when content is platform-specific - Use lowercase consistently

Keywords Field

# For simple posts
keywords:
  - docker tutorial
  - docker for beginners
  - install docker macos
  - docker compose tutorial

# For quests (structured)
keywords:
  primary:
    - docker tutorial
    - docker for beginners
  secondary:
    - container basics
    - docker compose
    - devops fundamentals

---

📄 Content Structure

Heading Hierarchy

# H1: Main Title (only one per page)

## H2: Major Sections
### H3: Subsections
#### H4: Detailed Points (use sparingly)

Rules: - One H1 per page (usually the title) - H2s contain keywords where natural - Logical hierarchy (don't skip levels) - Descriptive headings (not just "Introduction")

First Paragraph Optimization

The first 100-150 words are crucial:

# ❌ Bad Opening
In this tutorial, we'll look at Docker.

# ✅ Good Opening
Learn how to **install and configure Docker** on macOS, Linux, and Windows
with this step-by-step beginner's guide. By the end of this tutorial, you'll
understand containers, images, and Docker Compose—essential skills for modern
development and DevOps workflows.

Include: - Primary keyword in first sentence - What the reader will learn - Why it matters - Platform mentions if relevant

Code Blocks

Always specify the language:

# ❌ Bad

docker run hello-world

# ✅ Good
```bash
docker run hello-world

**Benefits**:
- Syntax highlighting
- Better accessibility
- Potential for rich snippets

### Internal Linking

Link to related content naturally:

```markdown
# ❌ No links
Learn about containers in this tutorial.

# ✅ With internal links
After completing this Docker tutorial, continue with our
[Docker Compose Quest](/quests/docker-compose/) to learn multi-container
applications, or review [Terminal Fundamentals](/quests/terminal-basics/)
if you need a refresher.

---

⚙️ Technical SEO

URL/Permalink Structure

# ❌ Bad permalinks
permalink: /post123/
permalink: /2024/03/27/docker/

# ✅ Good permalinks
permalink: /tutorials/docker-beginners-guide/
permalink: /quests/docker-compose-tutorial/

Rules: - Descriptive slugs with keywords - Hyphens between words (not underscores) - Lowercase only - No dates in URL (unless time-sensitive)

Draft Status

# ❌ Published content marked as draft
draft: true   # Content invisible to search engines!

# ✅ Ready for indexing
draft: false

CRITICAL: draft: true prevents indexing. Only use during active editing.

Lastmod Updates

# Always update when content changes
lastmod: 2025-12-19T00:00:00.000Z

Search engines use lastmod to prioritize crawling fresh content.

Image Optimization

# ❌ Bad
![](image.png)

# ✅ Good
![Docker architecture diagram showing containers, images, and registries](/assets/images/docker-architecture.png)

Rules: - Descriptive alt text for accessibility and SEO - Compressed images for fast loading - Descriptive filenames (docker-architecture.png not img1.png)

---

📊 Monitoring & Iteration

Key Metrics to Track

Metric	Source	Goal
CTR	Search Console	>2% for most pages
Impressions	Search Console	Trending upward
Position	Search Console	Top 10 for target keywords
Bounce Rate	Analytics	<70%
Time on Page	Analytics	>2 minutes for tutorials

Google Search Console Workflow

Weekly (5 minutes): 1. Check for crawl errors 2. Review top performing pages 3. Identify pages with high impressions but low CTR

Monthly (30 minutes): 1. Analyze keyword performance trends 2. Identify content gaps from search queries 3. Update underperforming pages 4. Track progress on optimized pages

When to Update Content

Update existing content when: - CTR < 1% with >100 impressions - Position 5-20 (almost on first page) - Outdated information (tools changed, new versions) - New keywords discovered from Search Console

---

✅ Quick Reference Checklist

Before Publishing

## Pre-Publish SEO Checklist

### Frontmatter
- [ ] Title: Under 60 chars, keyword at start
- [ ] Description: 150-160 chars, keyword included
- [ ] Tags: 5-10 relevant tags including platform
- [ ] Keywords: Primary search terms listed
- [ ] draft: false
- [ ] lastmod: Current date

### Content
- [ ] H1 is the title (only one)
- [ ] H2s contain keywords naturally
- [ ] First paragraph has primary keyword
- [ ] Code blocks have language specified
- [ ] Internal links to related content
- [ ] Images have alt text

### Technical
- [ ] Permalink is descriptive
- [ ] No broken links
- [ ] Images are compressed

SEO Quick Wins

When time is limited, prioritize:

1. Fix description: null - Biggest impact
2. Update titles to be keyword-rich
3. Change draft: true to false - Instant visibility
4. Add platform tags - Better targeting
5. Update lastmod - Signal freshness

---

🔗 Resources

Internal

• SEO Frontmatter Template
• TODO SEO Tracking
• Quick Actions

External

• Google Search Console
• Google's SEO Starter Guide
• Moz Beginner's Guide to SEO

---

Document Version: 1.0.0 Created: 2025-12-19 Last Updated: 2025-12-19 Owner: IT-Journey Team