# Internal Linking Process Improvements

**Last Updated:** 2026-03-03

## Summary

This document outlines improvements to the internal linking process based on review of the "Agiles Arbeiten" lexikon post and best practices analysis.

## Issues Identified

### 1. Duplicate Links
- **Problem:** Same link appearing multiple times (e.g., Fachkräftemangel appeared twice)
- **Impact:** Reduces link equity distribution, poor UX
- **Solution:** Always check for existing links before adding new ones

### 2. Missing Lexikon Links
- **Problem:** Topics mentioned but not linked (e.g., Recruiting, Organisationsentwicklung, Gleitzeit, Vertrauensarbeitszeit)
- **Impact:** Missed SEO opportunities, reduced topical clustering
- **Solution:** Use `suggest-contextual-links.php` and `audit-blog-lexikon-links.php --suggest-placements` to identify opportunities

### 3. Product Link Repetition
- **Problem:** Same product link repeated 3+ times (e.g., /arbeitszeiterfassung appeared 3 times)
- **Impact:** Over-optimization, poor UX
- **Solution:** Limit product links to 1-2 per post, vary anchor text

### 4. Missing Tool Links
- **Problem:** Calculable topics mentioned but no tool links (e.g., Urlaubsanspruch, SuE)
- **Impact:** Missed conversion opportunities
- **Solution:** Review `suggested-contextual-links.json` for tool opportunities

## Improved Process

### Step 1: Generate Suggestions (Mandatory)

```bash
# Generate all link opportunities
php v2/scripts/blog/suggest-contextual-links.php --post={slug} --category={category}
php v2/scripts/blog/suggest-ordio-feature.php --post={slug} --category={category}

# Get placement suggestions for missing links
php v2/scripts/blog/audit-blog-lexikon-links.php --post={slug} --category={category} --suggest-placements
```

### Step 2: Review Existing Links

**Check for:**
- Duplicate links (same URL appearing multiple times)
- Generic anchor text (improve to keyword-rich)
- Broken/redirected links (check canonical URLs)
- Over-linking (too many links in one paragraph)

**Tools:**
```bash
# Extract all links from content
grep -o 'href="[^"]*"' docs/content/blog/posts/{category}/{slug}/content-draft.html | sort | uniq -c | sort -rn
```

### Step 3: Add Missing Links Strategically

**Priority Order:**
1. **Lexikon links** (first meaningful mention) - Highest priority
2. **Tool links** (when calculable topic discussed) - Medium priority
3. **Industry links** (when industry mentioned) - Medium priority
4. **Product links** (contextual, 1-2 max) - Lower priority

**Guidelines:**
- Link on first meaningful mention (not forced)
- Use natural anchor text (topic name, not generic phrases)
- Maximum 1-2 links per paragraph
- Minimum 200 characters between links
- Avoid linking right after section titles

### Step 4: Reduce Product Link Repetition

**Before:**
```html
❌ <a href="/arbeitszeiterfassung">Ordio Zeiterfassung</a> (appears 3 times)
```

**After:**
```html
✅ First mention: "transparente <a href="/arbeitszeiterfassung">Zeiterfassung</a>"
✅ Second mention: "Arbeitszeiterfassung" (no link, already linked)
```

**Rule:** Link each product feature maximum 1-2 times per post. Use varied anchor text.

### Step 5: Validate Before Publishing

```bash
# Validate lexikon links
php v2/scripts/blog/audit-blog-lexikon-links.php --post={slug} --category={category}

# Validate tool links
php v2/scripts/blog/audit-blog-tool-links.php --post={slug} --category={category}

# Validate industry links
php v2/scripts/blog/audit-blog-industry-links.php --post={slug} --category={category}

# Full validation
php v2/scripts/blog/validate-new-post.php --post={slug} --category={category}
```

## Link Density Targets

### Current Best Practice
- **Total internal links:** 10-15 per post
- **Lexikon links:** 5-8 per post
- **Product links:** 1-2 per post (max 1-2 per feature)
- **Tool links:** 1-2 per post
- **Industry links:** 1-2 per post

### Distribution
- **Introduction:** 1-2 links
- **Main content:** 8-12 links (distributed throughout)
- **Conclusion:** 1-2 links (if appropriate)
- **FAQs:** 2-3 links total (not every FAQ needs a link)

## Quality Checklist

### Before Publishing
- [ ] No duplicate links (same URL appearing multiple times)
- [ ] All lexikon topics linked on first meaningful mention
- [ ] Product links limited to 1-2 per feature
- [ ] Tool links added for calculable topics
- [ ] Industry links added when industries mentioned
- [ ] Anchor text is natural and keyword-rich
- [ ] Links distributed throughout content (not clustered)
- [ ] Minimum 200 characters between links
- [ ] No links right after section titles
- [ ] All links use canonical URLs

### Validation Scripts
- [ ] `audit-blog-lexikon-links.php` passes
- [ ] `audit-blog-tool-links.php` passes
- [ ] `audit-blog-industry-links.php` passes
- [ ] `validate-new-post.php` passes (no blocking warnings)

## Process Integration

### New Post Creation Workflow

**After content draft, before validation:**

1. Run suggestion scripts
2. Review `suggested-contextual-links.json`
3. Review existing links (check for duplicates)
4. Add missing lexikon links (first meaningful mention)
5. Add tool/industry links (where relevant)
6. Reduce product link repetition (max 1-2 per feature)
7. Validate with audit scripts
8. Sync to JSON

### Content Improvement Workflow

**After content expansion:**

1. Run suggestion scripts (same as new posts)
2. Review existing links (remove duplicates, improve generic)
3. Add missing links from suggestions
4. Validate with audit scripts

## Examples

### Good Linking

```html
✅ "Im HR-Kontext kann Scrum für Personalentwicklungsprojekte, <a href="/insights/lexikon/recruiting/">Recruiting</a>-Kampagnen oder <a href="/insights/lexikon/organisationsentwicklung/">Organisationsentwicklung</a> eingesetzt werden."

✅ "Flexible <a href="/insights/lexikon/gleitzeit/">Gleitzeit</a> ermöglicht Teams, ihre Arbeitszeiten an Projektzyklen anzupassen."

✅ "Ordio unterstützt flexible Arbeitszeitmodelle: Die <a href="/schichtplan">Schichtplanung</a> ermöglicht flexible <a href="/insights/lexikon/schichtmodelle/">Schichtmodelle</a>."
```

### Bad Linking

```html
❌ "<a href="/insights/lexikon/fachkraeftemangel/">Fachkräftemangel</a>... <a href="/insights/lexikon/fachkraeftemangel/">Fachkräftemangel</a>" (duplicate)

❌ "<a href="/arbeitszeiterfassung">Ordio Zeiterfassung</a>... <a href="/arbeitszeiterfassung">Zeiterfassung</a>... <a href="/arbeitszeiterfassung">Arbeitszeiterfassung</a>" (3x same product)

❌ "Mehr zu Recruiting findest du im <a href="/insights/lexikon/recruiting/">Lexikon</a>." (forced phrase)
```

## Script Improvements Needed

### 1. Duplicate Detection
- **Current:** No automatic duplicate detection
- **Improvement:** Add duplicate link detection to `audit-blog-lexikon-links.php`
- **Output:** List of duplicate links with locations

### 2. Product Link Repetition Check
- **Current:** No check for product link repetition
- **Improvement:** Add product link repetition check to `validate-new-post.php`
- **Output:** Warning if same product link appears >2 times

### 3. Link Density Analysis
- **Current:** Manual counting
- **Improvement:** Add link density analysis to audit scripts
- **Output:** Total links, links per section, link distribution

### 4. Anchor Text Quality Check
- **Current:** Manual review
- **Improvement:** Add anchor text quality check (generic phrases detection)
- **Output:** List of generic anchor text suggestions for improvement

## Related Documentation

- [INTERNAL_LINKING_WORKFLOW_2026.md](INTERNAL_LINKING_WORKFLOW_2026.md) - Complete workflow
- [INTERNAL_LINKING_GUIDE.md](guides/INTERNAL_LINKING_GUIDE.md) - Detailed guide
- [CANONICAL_URLS_AND_LINKING.md](../../development/CANONICAL_URLS_AND_LINKING.md) - Canonical URL rules
- [blog-tool-linking.mdc](../../.cursor/rules/blog-tool-linking.mdc) - Tool linking rules

## Next Steps

1. **Update validation scripts** to detect duplicates and product repetition
2. **Add link density analysis** to audit scripts
3. **Create automated checks** for anchor text quality
4. **Update NEW_POST_LINKING_CHECKLIST.md** with improved process
5. **Review existing posts** for duplicate links and over-linking