# Tier 1 Posts Internal Linking Maintenance Guide

**Last Updated:** 2026-01-15

Guide for maintaining internal links in Tier 1 blog posts after initial enhancement.

## Overview

This guide provides instructions for maintaining internal links in Tier 1 posts, including when to add new links, how to update related posts, and how to add FAQ links and demo CTAs.

## When to Add New Links

### New Content Published

When new blog posts, tools, templates, or pages are published:

1. **Review Tier 1 Posts** for linking opportunities
2. **Check Related Posts** - Update `related_posts` array if new post is relevant
3. **Add Contextual Links** - Add links to new content where contextually relevant
4. **Update Pillar Pages** - If new content supports a pillar, consider adding links

### Content Updates

When updating existing Tier 1 post content:

1. **Review Link Relevance** - Ensure existing links are still relevant
2. **Add Missing Links** - Add links to new topics mentioned in updated content
3. **Remove Broken Links** - Remove or update links to deleted/moved content
4. **Update Anchor Text** - Improve anchor text if needed

### New Related Posts Identified

When new related posts are identified:

1. **Update `related_posts` Array** - Add to JSON file
2. **Add Link in Content** - Integrate link contextually in HTML content
3. **Use Varied Anchor Text** - Don't repeat anchor text from carousel

## How to Add New Links

### Manual Process

1. **Identify Opportunity**

   - Find contextually relevant mention in content
   - Determine appropriate anchor text
   - Check if link already exists

2. **Add Link to HTML**

   ```html
   <a href="/insights/category/slug">Descriptive Anchor Text</a>
   ```

3. **Update JSON File**
   - Update `content.html` field
   - Optionally add to `internal_links` array
   - Update `modified_date`

### Using Scripts

**Add Pillar Link:**

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

**Add Related Post Link:**

```bash
php v2/scripts/blog/integrate-related-posts-links-tier1.php --post={slug} --category={category}
```

**Add FAQ Link:**

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

## How to Update Related Posts

### Update `related_posts` Array

1. **Open Post JSON File**

   ```bash
   v2/data/blog/posts/{category}/{slug}.json
   ```

2. **Update `related_posts` Array**

   ```json
   {
     "related_posts": [
       {
         "slug": "new-related-post",
         "title": "New Related Post Title",
         "url": "/insights/category/new-related-post/",
         "category": "category",
         "similarity_score": 0.65,
         "relationship_type": "related"
       }
     ]
   }
   ```

3. **Add Link in Content**
   - Use `integrate-related-posts-links-tier1.php` script
   - Or manually add link contextually in HTML

### Remove Outdated Related Posts

1. **Review Related Posts** - Identify posts that are no longer relevant
2. **Remove from Array** - Remove from `related_posts` array
3. **Remove Link from Content** - Remove link from HTML content if exists

## How to Add FAQ Links

### Manual Process

1. **Identify FAQ Answer** - Find FAQ answer that mentions related topic
2. **Determine Link** - Identify appropriate internal link
3. **Add Link** - Insert link contextually in FAQ answer HTML
4. **Verify Limit** - Ensure FAQ answer has max 1-2 links

### Using Script

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

**Best Practices:**

- Maximum 1-2 links per FAQ answer
- Only link when answer > 50 characters
- Use descriptive anchor text
- Link to related topics, tools, or resources

## How to Add Demo CTAs

### Manual Process

1. **Identify CTA Opportunity** - Find text mentioning demo/trial
2. **Determine Style** - Inline (within paragraph) or standalone button
3. **Add Modal Button** - Use correct Alpine.js pattern

**Inline Style:**

```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>
```

**Standalone Style:**

```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-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"
>
  Demo vereinbaren
</button>
```

### Using Script

```bash
php v2/scripts/blog/convert-demo-ctas-tier1.php --post={slug} --category={category}
```

## Regular Maintenance Tasks

### Monthly

1. **Run Validation Script**

   ```bash
   php v2/scripts/blog/validate-tier1-links.php
   ```

2. **Review Validation Report**

   - Check for broken links
   - Review anchor text quality
   - Check for duplicates
   - Verify pillar links exist

3. **Fix Issues**
   - Update broken links
   - Improve generic anchor text
   - Remove duplicates
   - Add missing pillar links

### Quarterly

1. **Review Related Posts**

   - Update `related_posts` arrays
   - Add new related posts
   - Remove outdated related posts

2. **Review Link Quality**

   - Check link count per post
   - Verify link placement
   - Review anchor text variety

3. **Update Documentation**
   - Update enhancement checklist
   - Document changes made
   - Note improvements needed

## Quality Checklist

Before considering maintenance complete:

- [ ] All links functional
- [ ] Anchor text descriptive and varied
- [ ] No duplicate links
- [ ] Pillar links present where expected
- [ ] Related posts integrated
- [ ] FAQ links contextual (max 1-2 per answer)
- [ ] Demo CTAs use modal buttons
- [ ] Link count within target (10-15 per post)

## Troubleshooting

### Broken Links

**Issue:** Link returns 404 or redirects

**Solution:**

1. Check if target page exists
2. Verify URL is correct
3. Update link or remove if page deleted

### Duplicate Links

**Issue:** Same link appears multiple times

**Solution:**

1. Use validation script to identify duplicates
2. Remove redundant links
3. Keep only one link per target URL

### Generic Anchor Text

**Issue:** Anchor text is generic ("hier", "mehr")

**Solution:**

1. Replace with descriptive text
2. Use keyword-rich anchor text
3. Match anchor text to context

### Over-Linking

**Issue:** Too many links in one post

**Solution:**

1. Prioritize high-value links (pillar, related posts)
2. Remove redundant links
3. Focus on links that add value

## Related Documentation

- [Internal Linking Guide](guides/INTERNAL_LINKING_GUIDE.md)
- [Tier 1 Enhancement Process](TIER1_ENHANCEMENT_PROCESS.md)
- [Tier 1 Quality Checklist](TIER1_QUALITY_CHECKLIST.md)