# Internal Linking Guide for Blog Posts

**Last Updated:** 2026-04-01

## Overview

This guide provides comprehensive instructions for maintaining and improving internal linking across blog posts to optimize SEO/AEO/GEO performance.

## When to Add Links

### Always Add Links When:

1. **First Mention of Core Topics**

   - First mention of "Dienstplan" → Link to `/insights/dienstplan`
   - First mention of "Zeiterfassung" → Link to `/insights/zeiterfassung`
   - First mention of product features → Link to relevant product page

2. **Solution Recommendations**

   - When discussing problems → Link to relevant product pages
   - When mentioning tools → Link to relevant tools pages
   - When referencing resources → Link to templates or downloads

3. **Related Content**

   - When discussing related topics → Link to related blog posts
   - When mentioning industries → Link to industry pages
   - When comparing options → Link to comparison pages
   - **Lexikon 1:1 (Mandatory):** When a post mentions a term that has a dedicated lexikon post (primary_keyword match in `docs/data/blog-lexikon-mapping.json`), add a link on first meaningful mention. This is mandatory, not optional. Use natural anchor text (the topic name). Run `php v2/scripts/blog/audit-blog-lexikon-links.php --suggest-placements` to find gaps.

4. **FAQ Answers**
   - Add links in FAQ answers when relevant
   - Link to detailed guides or product pages

### Link Frequency Guidelines

**Word-Count-Based Total (2026 Best Practices):**

| Word Count | Min Links | Optimal | Max |
|------------|-----------|---------|-----|
| 500 | 3 | 2-3 | 4 |
| 1,000 | 4 | 4-5 | 7 |
| 1,500 | 5 | 6 | 10 |
| 2,000 | 7 | 8 | 14 |
| 3,000 | 10 | 12 | 20 |
| 4,000+ | 14+ | 16+ | 27-30 |

Formula: min = max(3, ceil(wc/300)); optimal = ceil(wc/250); max = min(30, ceil(wc/150)). Run `php v2/scripts/blog/audit-internal-link-density.php` to validate.

**1:1 Links Override Density (Mandatory):** Word-count targets are guidance, not caps. **Always add 1:1 related links** (lexikon, template, tool, product, pillar, ratgeber) when content mentions the term—even if that exceeds the suggested max. Never skip a 1:1 link to stay within targets. Posts above max due to 1:1 links are acceptable.

**By Link Type:**
- **Pillar Pages:** 1-2 links per post (mandatory for cluster posts; Dienstplan cluster → `/insights/dienstplan`, Zeiterfassung cluster → `/insights/zeiterfassung`)
- **Product Pages:** 1-3 links per post (when discussing solutions)
- **Blog Posts:** 2-5 links per post (to related content)
- **Tools Pages:** 1-2 links per post (when relevant)
- **Templates/Downloads:** 1 link per post (when mentioning resources)
- **Industry Pages:** 1 link per post (when industry-specific)

## How to Choose Anchor Text

### Best Practices

1. **Use Natural Language**

   - ✅ "gesetzeskonforme Zeiterfassung"
   - ❌ "click here for zeiterfassung"

2. **Include Keywords**

   - ✅ "Schichtplanung mit Ordio"
   - ❌ "hier"

3. **Vary Anchor Text**

   - Don't use the same anchor text multiple times
   - Use synonyms and variations

4. **Match Context**

   - Anchor text should fit naturally in the sentence
   - Use context-appropriate phrasing

5. **Respect Word Boundaries (Critical for German)**

   - ✅ Link "Checkliste" as a complete word
   - ❌ Don't link "Checkliste" inside "Checklisten" (plural)
   - ✅ Link "Schichtplanung" as a complete word
   - ❌ Don't link "Schichtplanungs" inside "Schichtplanungsfunktionen" (compound word)
   - **Rule:** Always link complete words, never parts of compound words or plural forms
   - **Technical:** All linking scripts use German-aware word boundary matching to prevent partial-word links

6. **Avoid Generic Patterns**
   - ❌ "mehr zu dienstplan" (awkward, grammatically incorrect)
   - ❌ "weitere Informationen zu zeiterfassung" (too generic, doesn't fit naturally)
   - ✅ "Dienstplan erstellen" (natural, descriptive)
   - ✅ "gesetzeskonforme Zeiterfassung" (contextual, valuable)
   - **Rule:** Never use generic patterns like "mehr zu [word]" or "weitere Informationen zu [word]" - these create awkward, grammatically incorrect anchor texts that don't fit naturally into content

7. **Never Add Forced Link Phrases**
   - ❌ "Mehr dazu im Lexikon-Artikel zur Überstunden."
   - ❌ "Mehr zum Feiertagszuschlag erfährst du in unserem Lexikon."
   - ❌ "Details findest du im Lexikon Akkordarbeit."
   - ✅ Link the term where it already appears naturally in the content
   - **Rule:** Only link terms that are already present in the content. Never add new phrases solely to create links. If a topic is mentioned naturally, link that occurrence. If it is not mentioned, do not force it in with a "Mehr dazu im Lexikon X" or similar phrase.

### Anchor Text Examples

**Pillar Pages:**

- "Dienstplan"
- "umfassender Leitfaden zum Dienstplan"
- "Dienstplan erstellen"

**Product Pages:**

- "Schichtplanung mit Ordio"
- "Zeiterfassungssoftware"
- "digitale Lohnabrechnung"

**Tools:**

- "Arbeitszeitrechner"
- "kostenloser Urlaubsrechner"

**Templates:**

- "kostenlose Dienstplan Excel Vorlage"
- "Schichtplan Vorlage"

## Where to Place Links

### Placement Rules by Link Type

1. **Pillar Pages**

   - First mention in content
   - Introduction section
   - Summary section

2. **Product Pages**

   - CTA sections
   - Solution recommendations
   - Tool mentions

3. **Industry Pages**

   - Industry-specific mentions
   - Case study sections

4. **Tools Pages**

   - Calculation examples
   - How-to sections

5. **Templates/Downloads**

   - Resource sections
   - Download CTAs

6. **Blog Posts**
   - Related content sections
   - Natural content flow

## Link Quality Standards

### Checklist

- [ ] Anchor text is descriptive and keyword-rich
- [ ] Anchor text is natural and fits context
- [ ] Link is contextually relevant
- [ ] Link adds value for the reader
- [ ] Anchor text is varied (not repeated)
- [ ] Link is placed in appropriate section
- [ ] Link frequency is appropriate (not excessive)
- [ ] **Word boundaries are respected (no partial-word links)**
- [ ] **Link fits grammatically into sentence**
- [ ] **Link is not placed right after section titles**
- [ ] **Link is not placed at end of paragraph (unless conclusion/CTA)**
- [ ] **No redundant links in close proximity**

### Avoid

- ❌ Generic phrases ("click here", "read more")
- ❌ **URLs or slugs as anchor text** – Never use bare links like `/partner`, `/partner/register`, or any path as the visible anchor. Always use natural, contextual anchor text (e.g. "Partner-Seite", "hier anmelden", "kostenlose Partner-Anmeldung").
- ❌ Over-optimization (exact-match keywords only)
- ❌ Too many links in one paragraph
- ❌ Links that don't add value
- ❌ **Partial-word links** (e.g., linking "Checkliste" inside "Checklisten" or "Schichtplanungs" inside "Schichtplanungsfunktionen")
- ❌ **Generic patterns** ("mehr zu dienstplan", "weitere Informationen zu zeiterfassung") - These create awkward, grammatically incorrect anchor texts that don't fit naturally into content
- ❌ **Random anchor texts** - Links should be contextually relevant and add value, not just fill quotas
- ❌ **Link dumps** – Never append "Weitere Lexikon-Artikel:", "Weitere Artikel zu verwandten Themen:" or similar phrases with a list of links at the end of a paragraph or section. Integrate links naturally within the flow of content and FAQ answers, using contextual anchor text that fits the sentence. The related-posts carousel handles discovery; inline links must add value in context.

## Overlapping Terms (Lexikon + Template + Product)

When a term has multiple valid link targets, add **all** contextually relevant links—do not choose one over another:

| Term | Lexikon | Template | Product | Ratgeber | Pillar |
|------|---------|----------|---------|----------|--------|
| Stundenzettel | `/insights/lexikon/stundenzettel/` | `/vorlagen/stundenzettel-excel-vorlage` | `/arbeitszeiterfassung` | — | — |
| Schichtplan | — | `/vorlagen/schichtplan-excel-vorlage` | `/schichtplan` | `/insights/ratgeber/schichtplan-erstellen/` | — |
| Schichtplanung | — | — | `/schichtplan` | `/insights/ratgeber/schichtplan-erstellen/` | `/insights/dienstplan` |
| Dienstplan | — | `/vorlagen/dienstplan-excel-vorlage` | `/schichtplan` | `/insights/ratgeber/dienstplan-erstellen/` | `/insights/dienstplan` |
| Zeiterfassung | — | — | `/arbeitszeiterfassung` | — | `/insights/zeiterfassung` |

**Guidance:** Definition/explanation → lexikon; download/Vorlage → template; product feature → product; how-to guide → ratgeber; topic overview → pillar. Add each on its first contextually appropriate mention. See `docs/data/blog-overlapping-terms.json`.

## Content Cluster Considerations

### Cluster-to-Pillar Linking

- **Dienstplan cluster** → Always link to `/insights/dienstplan`
- **Zeiterfassung cluster** → Always link to `/insights/zeiterfassung`

### Cluster-to-Product Linking

- **Dienstplan cluster** → Link to `/schichtplan`
- **Zeiterfassung cluster** → Link to `/arbeitszeiterfassung`
- **Lohnabrechnung cluster** → Link to `/payroll` (Ordio Payroll)

### Product Feature Links (Contextual Promotion)

Match the product page link to the content topic. Do not default to Zeiterfassung/Dienstplan when another feature fits. See [ORDIO_PROMOTION_GUIDE](../ORDIO_PROMOTION_GUIDE.md) for full guidance.

| First Mention Of | Product Page | Example Anchor |
|------------------|--------------|----------------|
| Urlaub, Abwesenheit, Krankmeldung | `/abwesenheiten` | "Urlaubsanträge verwalten", "Abwesenheiten" |
| Lohnabrechnung, Lohnarten, Gehalt | `/payroll` (Ordio Payroll) | "Ordio Payroll", "digitale Lohnabrechnung", "Lohnabrechnungen erstellen" |
| Personalakte, Stammdaten, Mitarbeiterdaten | `/digitale-personalakte` | "digitale Personalakte", "Mitarbeiterdaten" |
| Dokumente, Arbeitsvertrag | `/dokumentenmanagement` | "Dokumentenmanagement", "Dokumente verwalten" |
| Checkliste, HACCP, Reinigungsplan | `/checklisten` | "digitale Checklisten", "HACCP-Checklisten" |
| Event, Festival, Messe, Veranstaltung | `/events` | "Eventpersonal", "Veranstaltungsplanung" |
| Zeiterfassung, Arbeitszeiten | `/arbeitszeiterfassung` | "Zeiterfassung", "digitale Zeiterfassung" |
| Dienstplan, Schichtplan, Personaleinsatz | `/schichtplan` | "Dienstplan", "Schichtplanung" |
| Integration, POS, Kassensystem | `/app-store` | "App Store", "Integrationen" |

Full mapping: `docs/data/blog-product-feature-mapping.json`. Run `php v2/scripts/blog/audit-ordio-promotion.php` to find gaps.

### Cross-Cluster Linking

- Link between related clusters when topics overlap
- Use semantic similarity to guide linking

### Blog-to-Tool Linking

When a blog post discusses a topic that has a matching calculator/tool, add 1 contextual link to the relevant tool. Use natural anchor text (e.g. "kostenlosen Midijob-Rechner").

| Topic | Tool URL | Example Anchor |
|-------|----------|----------------|
| Midijob, Gleitzone, Übergangsbereich | `/tools/midijob-rechner/` | "kostenlosen Midijob-Rechner" |
| Minijob, 450-Euro-Job | `/tools/minijob-rechner/` | "kostenlosen Minijob-Rechner" |
| Brutto-Netto, Gehaltsberechnung | `/tools/brutto-netto-rechner/` | "Brutto-Netto-Rechner" |
| Lohnabrechnung (when calculation focus) | `/tools/brutto-netto-rechner/`, `/tools/midijob-rechner/` | "Gehaltsrechner", "Midijob-Rechner" |
| Arbeitslosengeld, ALG 1 | `/tools/arbeitslosengeld-rechner/` | "Arbeitslosengeld-Rechner" |
| Kurzarbeit, Kurzarbeitergeld, KUG | `/tools/kurzarbeitergeld-rechner` | "Kurzarbeitergeld-Rechner", "KUG schätzen" |
| Urlaubsanspruch | `/tools/urlaubsanspruch-rechner/` | "Urlaubsanspruch-Rechner" |
| Arbeitstage | `/tools/arbeitstage-rechner/` | "Arbeitstage-Rechner" |
| Zeiterfassung/Überstunden | `/tools/arbeitszeitrechner/` | "Arbeitszeitrechner" |
| Schichtbetrieb, Compliance | `/shiftops` | "ShiftOps" |

### Topic-to-Tool Mapping (Extended)

| Topic | Tool URL | Example Anchor |
|-------|----------|----------------|
| TVöD, öffentlicher Dienst, SuE, Erzieher, Sozialpädagogen | `/tools/tvoed-sue-gehaltsrechner/` | "TVöD-SuE Gehaltsrechner" |
| Zuschläge, Zuschlagsberechnung, Nachtarbeit, Feiertagsarbeit, Sonntagsarbeit | `/tools/zuschlagsrechner/` | "Zuschlagsrechner" |
| Industrieminuten, Dezimalzeit, REFA | `/tools/industrieminuten-rechner/` | "Industrieminuten-Rechner" |
| Stundenlohn, Mindestlohn | `/tools/stundenlohnrechner/` | "Stundenlohnrechner" |
| Einkommensteuer, Steuerklassen | `/tools/einkommensteuer-rechner/` | "Einkommensteuer-Rechner" |
| Elterngeld, Elternzeit, BEEG, Basiselterngeld, ElterngeldPlus | `/tools/elterngeldrechner` | "kostenloser Elterngeld-Rechner" |

### Topic-to-Industry Mapping

When content mentions specific industries (Einzelhandel, Gastronomie, DEHOGA, Baugewerbe, etc.), add a contextual link to the corresponding industry page per `docs/data/blog-industry-mapping.json`.

| Topic | Industry URL | Example Anchor |
|-------|--------------|----------------|
| Einzelhandel | `/branchen/einzelhandel` | "Einzelhandel" |
| Gastronomie, DEHOGA, Hotel, Restaurant | `/branchen/gastronomie` | "Gastronomie" |
| Pflege, Gesundheitswesen, Krankenhaus | `/branchen/gesundheitswesen` | "Gesundheitswesen" |
| Handwerk, Industrie, Baugewerbe | `/branchen/handwerk-industrie` | "Handwerk", "Baugewerbe" |
| Event, Freizeit, Kultur | `/branchen/freizeit-kultur` | "Freizeit-Kultur" |

**Checklist:** When post mentions [midijob, minijob, brutto-netto, urlaub, arbeitslosengeld, kurzarbeit, kurzarbeitergeld, KUG, TVöD, Zuschläge, Einzelhandel, Gastronomie, etc.], add 1 contextual link to the relevant tool or industry page with natural anchor text. When post mentions a topic with a dedicated lexikon post (e.g. Soft Skills, Nachfolgeplanung), add a link on first meaningful mention. See `docs/data/blog-tool-mapping.json`, `docs/data/blog-industry-mapping.json`, and `docs/data/blog-lexikon-mapping.json` for full mappings. Run `php v2/scripts/blog/audit-blog-tool-links.php`, `php v2/scripts/blog/audit-blog-industry-links.php`, and `php v2/scripts/blog/audit-blog-lexikon-links.php` to find gaps.

## Maintenance Process

### When Adding New Posts

1. Identify primary cluster
2. Add links to relevant pillar page
3. Add links to relevant product pages
4. Add links to related blog posts
5. Add links to relevant tools/templates
6. Add links in FAQs if relevant

### When Updating Existing Posts

1. Review existing links
2. Check for broken links
3. Improve anchor text if needed
4. Add missing links based on content
5. Remove irrelevant links

### Regular Audits

- Run link validation script monthly
- Review anchor text variety
- Check cluster coverage
- Update based on new content

### Bulk Link Enrichment (Pre-existing Posts)

To add contextual links across all posts in bulk:

1. **Generate suggestions:** `php v2/scripts/blog/suggest-contextual-links.php --all`
2. **Dry-run:** `php v2/scripts/blog/add-contextual-links-from-suggestions.php --all --dry-run [--lexikon-only]`
3. **Apply:** `php v2/scripts/blog/add-contextual-links-from-suggestions.php --all [--lexikon-only] [--limit=N]`
4. **Verify:** Run audits; remaining gaps may need manual review (topic inside existing link, edge cases)

**When adding new lexikon posts:** Run `php v2/scripts/blog/generate-blog-lexikon-mapping.php` before suggest/audit.

## Tools and Scripts

### Available Scripts

- `extract-all-links.py` - Extract and categorize all links
- `validate-all-links.py` - Validate link health and quality
- `audit-seo-practices.py` - SEO/AEO/GEO best practices audit
- `validate-clusters.py` - Cluster linking validation
- `generate-link-recommendations.php` - Generate link suggestions
- `audit-blog-tool-links.php` - Audit tool link gaps (use `--suggest-placements` for anchor/context)
- `audit-blog-industry-links.php` - Audit industry link gaps
- `audit-blog-lexikon-links.php` - Audit lexikon-to-lexikon link gaps (use `--suggest-placements` for context)
- `generate-blog-lexikon-mapping.php` - Regenerate topic-to-lexikon mapping (run after adding new lexikon posts)
- `add-contextual-links-from-suggestions.php` - Add suggested tool/industry/lexikon links in bulk (requires suggest-contextual-links --all first)
- `remove-forced-link-patterns.php` - Remove forced link phrases (e.g. "Mehr dazu im Lexikon X") and link terms where they appear naturally
- `suggest-new-links.php` - Suggest tool/industry links from mappings
- `suggest-contextual-links.php` - Per-post tool/industry/lexikon suggestions (output: data/suggested-contextual-links.json)
- `suggest-ordio-feature.php` - Product feature + tool + industry suggestions

### Usage

```bash
# Extract all links
python3 v2/scripts/blog/extract-all-links.py

# Validate links
python3 v2/scripts/blog/validate-all-links.py

# Audit tool links (with placement suggestions)
php v2/scripts/blog/audit-blog-tool-links.php [--suggest-placements]

# Audit industry links
php v2/scripts/blog/audit-blog-industry-links.php

# Suggest links for a specific post
php v2/scripts/blog/suggest-contextual-links.php --post=slug --category=lexikon
php v2/scripts/blog/suggest-ordio-feature.php --post=slug --category=lexikon

# Suggest links for ALL posts (audit pre-existing posts)
php v2/scripts/blog/suggest-contextual-links.php --all

# Audit lexikon-to-lexikon links (regenerate mapping first if new lexikon posts added)
php v2/scripts/blog/generate-blog-lexikon-mapping.php
php v2/scripts/blog/audit-blog-lexikon-links.php [--suggest-placements]

# Add suggested links in bulk (run suggest-contextual-links --all first)
php v2/scripts/blog/add-contextual-links-from-suggestions.php --all [--dry-run] [--lexikon-only] [--limit=N]

# Audit SEO practices
python3 v2/scripts/blog/audit-seo-practices.py

# Validate clusters
python3 v2/scripts/blog/validate-clusters.py
```

## Decision Tree

```
Is this the first mention of a core topic?
├─ Yes → Add pillar page link
└─ No → Continue

Is this a solution recommendation?
├─ Yes → Add product page link
└─ No → Continue

Is this mentioning a tool or calculation?
├─ Yes → Add tools page link
└─ No → Continue

Is this mentioning a resource or template?
├─ Yes → Add template/download link
└─ No → Continue

Is this related to a specific industry?
├─ Yes → Add industry page link
└─ No → Continue

Is this related to another blog post?
├─ Yes → Add blog post link
└─ No → Skip
```

## Examples

### Good Link Placement

**Example 1: Pillar Link**

```html
<p>
  Die <a href="/insights/dienstplan">Dienstplanung</a> ist ein wichtiger
  Bestandteil der Personalverwaltung.
</p>
```

**Example 2: Product Link**

```html
<p>
  Für die digitale Schichtplanung kannst du
  <a href="/schichtplan">Schichtplanung mit Ordio</a> nutzen.
</p>
```

**Example 3: Tool Link**

```html
<p>
  Berechne deinen Urlaubsanspruch mit unserem
  <a href="/tools/urlaubsanspruch-rechner">kostenlosen Urlaubsrechner</a>.
</p>
```

### Poor Link Placement

**Example 1: Generic Anchor**

```html
<p>Mehr Informationen findest du <a href="/insights/dienstplan">hier</a>.</p>
```

**Example 2: Over-Optimization**

```html
<p>
  Die <a href="/schichtplan">Schichtplanung Dienstplan Software</a> ist wichtig.
</p>
```

## German Umlaut and ASCII Handling

**Slugs use ASCII** (ue, ae, oe, ss) for canonical URLs; **content uses proper German** (ü, ä, ö, ß). Internal linking must match both forms.

### Mapping and Matching

| Form | Use | Example |
|------|-----|---------|
| **URL/slug** | Canonical, ASCII only | `fuehrungsstile` |
| **Mapping keys** | Umlaut form (for matching content) | `Führungsstile` |
| **Content** | Typically proper German | "Führungsstile" |

- **generate-blog-lexikon-mapping.php** uses `slugToSearchKeyword()` when falling back to slug, so mapping keys are umlaut form.
- **contentContainsKeywordWithBoundary** and **add-contextual-links** use `getKeywordMatchVariants()` to match both umlaut and ASCII forms in content.
- Config: `v2/config/blog-umlaut-redirects.php` and `docs/systems/landing-page-redirects/LEXIKON_UMLAUT_REDIRECTS.md`.

### Best Practice

- **primary_keyword** in posts: Use umlaut form (Führungsstile) for SEO research and mapping.
- **Links in content**: Always use canonical ASCII URLs (`/insights/lexikon/fuehrungsstile/`).

## German Word Boundary Handling

### Technical Implementation

All linking scripts use German-aware word boundary matching to prevent partial-word links:

**Python Scripts:**

- Use `link_utils.py` with `german_word_boundary_pattern()` function
- Pattern: `(?<![a-zA-ZäöüÄÖÜß])keyword(?![a-zA-ZäöüÄÖÜß])`
- Ensures keywords are matched as complete words, not substrings

**PHP Scripts:**

- Use `link_utils.php` with `germanWordBoundaryPattern()` function
- Pattern: `/(?<![\p{L}])keyword(?![\p{L}])/ui`
- Unicode-aware matching for all letter characters

### Common Issues Prevented

1. **Plural Forms:** "Checkliste" won't match inside "Checklisten"
2. **Compound Words:** "Schichtplanungs" won't match inside "Schichtplanungsfunktionen"
3. **German Characters:** Properly handles ä, ö, ü, ß in word boundaries

### Audit and Fix Tools

- **Audit:** `v2/scripts/blog/audit-partial-word-links.py` - Identifies problematic links
- **Fix:** `v2/scripts/blog/fix-partial-word-links.py` - Automatically fixes issues
- **Run monthly:** Check for any new partial-word links introduced

## Orphaned Anchor Text Handling

When removing problematic links, some anchor text should be removed entirely rather than kept as plain text. This prevents awkward orphaned text from appearing in content.

### Patterns That Should Be Removed

1. **"mehr zum/zur" patterns**: Text like "mehr zum Dienstplan" after section titles

   - Example: `<p><strong>Ein Beispiel aus der Praxis:</strong> mehr zum Dienstplan</p>`
   - Should become: `<p><strong>Ein Beispiel aus der Praxis:</strong></p>`

2. **Single words at end of sentences**: Orphaned anchor text like "Checkliste" after a period

   - Example: `<p>Sentence. Checkliste</p>`
   - Should become: `<p>Sentence.</p>`

3. **Text after colons**: Awkward standalone text after section headings
   - Example: `<p><strong>Title:</strong> mehr zum Dienstplan</p>`
   - Should become: `<p><strong>Title:</strong></p>`

### When to Keep Anchor Text

Keep anchor text when it's natural, contextually appropriate text that flows with the content:

- Full sentences or phrases that make sense standalone
- Natural keywords that enhance readability
- Text that completes a thought or sentence

### Tools

- `v2/scripts/blog/fix-problematic-links.php` - Automatically removes orphaned text when fixing problematic links
- `v2/scripts/blog/remove-orphaned-text.php` - Cleanup script for existing orphaned text
- `v2/scripts/blog/identify-orphaned-text.php` - Identify orphaned text patterns

## Tier 1 Posts Specific Guidelines

### Pillar Linking Requirements

**CRITICAL:** All Tier 1 posts must link to relevant pillar pages based on their content clusters:

- **Dienstplan cluster posts** → Must link to `/insights/dienstplan`
- **Zeiterfassung cluster posts** → Must link to `/insights/zeiterfassung`
- **Posts in both clusters** → Should link to both pillar pages

**Placement:**

- Place pillar links early in content (within first third)
- Use descriptive anchor text (see examples below)
- Avoid duplicates (only one link per pillar per post)

**Anchor Text Examples:**

- "Dienstplan"
- "mehr zum Dienstplan"
- "umfassender Leitfaden zum Dienstplan"
- "Zeiterfassung"
- "mehr zur Zeiterfassung"
- "digitale Zeiterfassung"

### Related Posts Integration

**CRITICAL:** Related posts from the `related_posts` carousel should be integrated into content HTML:

- **Target:** Link 5-8 high-similarity related posts per post
- **Placement:** Contextually distributed throughout content (not all at end)
- **Anchor Text:** Use varied anchor text based on post titles
- **Priority:** Prioritize posts with similarity scores > 0.4

**Best Practices:**

- Don't link all related posts - focus on highest similarity
- Place links where contextually relevant
- Use natural anchor text variations

### FAQ Linking Best Practices

**For Tier 1 posts with FAQ sections:**

- **Maximum:** 1-2 contextual internal links per FAQ answer
- **When to Link:** Answers > 50 characters that mention related topics, tools, or resources
- **Anchor Text:** Use descriptive, keyword-rich anchor text
- **Avoid:** Generic phrases like "click here" or "mehr erfahren"

**Examples:**

- FAQ mentions "Zeiterfassung" → Link to `/insights/zeiterfassung`
- FAQ mentions "Dienstplan Software" → Link to `/schichtplan`
- FAQ mentions "Urlaubsrechner" → Link to `/tools/urlaubsanspruch-rechner`

### Demo CTA Patterns

**CRITICAL:** All demo/trial CTAs in Tier 1 posts must use Alpine.js modal buttons:

**Pattern:**

```html
<button
  type="button"
  data-event-type="button_click"
  data-event-name="Demo vereinbaren"
  @click="$store.modal.open('Unverbindliche Demo vereinbaren', 'Unverbindliche Demo vereinbaren')"
  class="font-inter500 text-ordio-blue hover:text-blue-600 underline cursor-pointer bg-transparent border-none p-0"
>
  Demo vereinbaren
</button>
```

**Never Use:**

- Links to `/demo-vereinbaren`
- Links to `https://www.ordio.com/demo-vereinbaren`
- Local Alpine.js variables

**Styling:**

- **Inline (within paragraphs):** `font-inter500 text-ordio-blue hover:text-blue-600 underline cursor-pointer bg-transparent border-none p-0`
- **Standalone buttons:** `font-inter500 text-sm sm:text-base bg-white border border-[#EDEFF3] text-[#333] hover:bg-gray-50 shadow-md hover:shadow-lg p-4 px-6 rounded-full transition-all duration-200 min-h-[48px] inline-flex items-center justify-center`

### Tier 1 Link Quality Targets

- **Link Count:** 10-15 internal links per post (minimum)
- **Pillar Links:** 100% of relevant posts have pillar links
- **Related Posts:** 80%+ of related posts linked in content
- **FAQ Links:** 60%+ of FAQ answers have contextual links (where relevant)
- **Demo CTAs:** 100% use modal buttons
- **Anchor Text:** 0 generic anchors
- **Duplicates:** 0 duplicate links per post

### Enhancement Scripts

Use these scripts for Tier 1 post enhancements:

- `add-pillar-links-tier1.php` - Add pillar page links
- `integrate-related-posts-links-tier1.php` - Integrate related posts
- `enhance-faq-links-tier1.py` - Enhance FAQ links
- `convert-demo-ctas-tier1.php` - Convert demo CTAs
- `validate-tier1-links.php` - Validate all links

**Always use `--dry-run` first to preview changes.**

## Related Documentation

- [Anchor Text Guidelines](./ANCHOR_TEXT_GUIDELINES.md)
- [Link Placement Guide](./LINK_PLACEMENT_GUIDE.md)
- [Target Pages Guide](./TARGET_PAGES_GUIDE.md)
- [Cluster Linking Strategy](./CLUSTER_LINKING_STRATEGY.md)
- [Orphaned Text Fix](./ORPHANED_TEXT_FIX.md)
- [Tier 1 Enhancement Process](../TIER1_ENHANCEMENT_PROCESS.md)
- [Tier 1 Quality Checklist](../TIER1_QUALITY_CHECKLIST.md)