# Pillar Page Integration Checklist

**Last Updated:** 2026-01-18

Step-by-step checklist for verifying and implementing pillar page integration in blog posts.

## Overview

Pillar pages are main topic pages that serve as hubs for content clusters. All posts that belong to a content cluster must link to their pillar page(s) to strengthen site architecture, improve SEO, and enhance user navigation.

## Available Pillar Pages

- `/insights/dienstplan/` - Dienstplan pillar (Dienstplan cluster)
- `/insights/zeiterfassung/` - Zeiterfassung pillar (Zeiterfassung cluster)

## Step-by-Step Checklist

### Step 1: Check Pillar Page Mapping

**Action:** Identify which pillar page(s) the post should link to

**Process:**

1. Open `docs/content/blog/TIER1_PILLAR_MAPPING.md`
2. Find the post slug in the mapping
3. Note which pillar page(s) are listed for that post
4. Some posts belong to multiple clusters and should link to multiple pillar pages

**Checklist:**

- [ ] Pillar mapping file reviewed
- [ ] Post slug found in mapping
- [ ] Pillar page(s) identified
- [ ] Multiple pillars noted (if applicable)

**Example:**

- `dienstplan-gesetz` → Should link to both `/insights/dienstplan` and `/insights/zeiterfassung`
- `arbeitsstunden-pro-monat` → Should link to `/insights/zeiterfassung`
- `24-stunden-schicht` → Should link to `/insights/dienstplan`

### Step 2: Add Pillar Links to Internal Links Array

**Action:** Add pillar page link(s) to `internal_links` array in JSON file

**Process:**

1. Open post JSON file: `v2/data/blog/posts/{category}/{slug}.json`
2. Locate `internal_links` array
3. Add new entry for each pillar page that should be linked
4. Use proper metadata structure

**Required Metadata:**

```json
{
    "url": "/insights/zeiterfassung",
    "normalized_url": "/insights/zeiterfassung",
    "anchor_text": "digitale Zeiterfassung",
    "target_type": "pillar-page",
    "priority": "critical",
    "added_at": "2026-01-18 12:00:00",
    "reasoning": "Cluster requirement: post belongs to Zeiterfassung cluster, should link to Zeiterfassung pillar page"
}
```

**Checklist:**

- [ ] JSON file opened
- [ ] `internal_links` array located
- [ ] Pillar link entry added with all required fields
- [ ] Anchor text is natural and contextual
- [ ] `target_type` set to `"pillar-page"`
- [ ] `priority` set to `"critical"`
- [ ] `reasoning` field completed

### Step 3: Add Contextual Link in Content HTML

**Action:** Add natural pillar page link in content HTML where topic is discussed

**Process:**

1. Review content HTML in JSON file
2. Identify natural placement opportunities:
   - First 20% of content (definition/introduction section)
   - Middle sections where topic is discussed in detail
   - Resource sections ("Weiterführende Ressourcen" or similar)
3. Add link with natural anchor text that flows within sentence
4. Avoid footer-only placement (should be contextual)

**Placement Guidelines:**

- ✅ First 20%: Definition/introduction section
- ✅ Middle sections: Where topic is discussed in detail
- ✅ Resource sections: "Weiterführende Ressourcen" or similar
- ❌ Footer-only placement (should be contextual)

**Anchor Text Examples:**

✅ "Wenn du digitale Lösungen wie [digitale Zeiterfassung](/insights/zeiterfassung) verwendest..."
✅ "Moderne [Zeiterfassungssysteme](/insights/zeiterfassung) unterstützen..."
✅ "Die Integration mit der [Zeiterfassung](/insights/zeiterfassung) sorgt..."

**Checklist:**

- [ ] Content HTML reviewed
- [ ] Natural placement opportunity identified
- [ ] Link added with natural anchor text
- [ ] Link flows naturally within sentence
- [ ] Not placed only in footer

### Step 4: Add Pillar Pages to Related Posts Array

**Action:** Add pillar page(s) to `related_posts` array at the beginning (top 3-5 positions)

**Process:**

1. Open post JSON file: `v2/data/blog/posts/{category}/{slug}.json`
2. Locate `related_posts` array
3. Add pillar page entry at the beginning (before other related posts)
4. Use proper metadata structure with high similarity score

**Required Metadata:**

```json
{
    "slug": "zeiterfassung",
    "title": "Zeiterfassung einfach erklärt – Tools und Tipps | Ordio",
    "url": "/insights/zeiterfassung/",
    "category": "pillar",
    "similarity_score": 0.90,
    "relationship_type": "pillar_page"
}
```

**Priority:** Pillar pages should appear in top 3-5 related posts for better visibility.

**Checklist:**

- [ ] JSON file opened
- [ ] `related_posts` array located
- [ ] Pillar page entry added at beginning (top 3-5 positions)
- [ ] All required fields included
- [ ] `category` set to `"pillar"`
- [ ] `relationship_type` set to `"pillar_page"`
- [ ] `similarity_score` set to 0.85-0.90 (high visibility)
- [ ] Title matches pillar page title exactly

### Step 5: Validation

**Action:** Verify all changes are correct

**Process:**

1. Validate JSON syntax
2. Verify all pillar links are present
3. Verify contextual links exist in content HTML
4. Run validation script

**Validation Script:**

```bash
php v2/scripts/blog/validate-pillar-links.php --post={slug} --category={category}
```

**Manual Checks:**

- [ ] JSON file syntax is valid
- [ ] Pillar link(s) present in `internal_links` array
- [ ] Contextual pillar link(s) present in content HTML
- [ ] Pillar page(s) present in `related_posts` array (top positions)
- [ ] All URLs are correct (include trailing slash for pillar pages)
- [ ] All metadata fields are complete
- [ ] Validation script run and passing

## Common Issues and Solutions

### Issue: Post Not Found in Pillar Mapping

**Solution:** Check if post belongs to a cluster. If not, no pillar link required. If yes, add to mapping first.

### Issue: Wrong Pillar Page Linked

**Solution:** Review `TIER1_PILLAR_MAPPING.md` to confirm correct pillar page. Update link if incorrect.

### Issue: Pillar Page Missing from Related Posts

**Solution:** Add pillar page to `related_posts` array at the beginning with high similarity score (0.85-0.90).

### Issue: Contextual Link Not Natural

**Solution:** Review content HTML and ensure link flows naturally within sentence. Avoid forced placement.

## Reference Documents

- `docs/content/blog/TIER1_PILLAR_MAPPING.md` - Pillar mapping for all posts
- `docs/content/blog/PILLAR_INTEGRATION.md` - Pillar integration analysis
- `docs/content/blog/INTERNAL_LINKING_IMPROVEMENT_GUIDE.md` - Internal linking guide
- `.cursor/rules/content-clusters.mdc` - Content cluster patterns
- `.cursor/rules/pillar-pages.mdc` - Pillar page patterns

## Quick Reference

**Pillar Page URLs:**

- Dienstplan: `/insights/dienstplan/`
- Zeiterfassung: `/insights/zeiterfassung/`

**Pillar Page Titles:**

- Dienstplan: "Dienstplan 2026: Definition, Erstellung & Software - Ordio"
- Zeiterfassung: "Zeiterfassung einfach erklärt – Tools und Tipps | Ordio"

**Required Fields:**

- `internal_links`: `url`, `normalized_url`, `anchor_text`, `target_type`, `priority`, `reasoning`
- `related_posts`: `slug`, `title`, `url`, `category`, `similarity_score`, `relationship_type`