# Internal Linking Process

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

End-to-end process for adding and maintaining internal links in new and existing blog posts.

## Overview

1. **Identify linkable resources** from mapping files
2. **Run audit and suggestion scripts** to find gaps
3. **Apply links** via `update-post-content.php` (never edit JSON directly)
4. **Validate** with audit scripts and `validate-new-post.php`

## Mapping Files

| File | Purpose |
|------|---------|
| `docs/data/blog-tool-mapping.json` | Topic → tool URL (midijob, TVöD, Zuschläge, etc.) |
| `docs/data/blog-industry-mapping.json` | Topic → industry page (Einzelhandel, Gastronomie, etc.) |
| `docs/data/blog-product-feature-mapping.json` | Topic → product page (Zeiterfassung, Payroll, etc.) |

## Scripts

| Script | Purpose | Output |
|--------|---------|--------|
| `audit-blog-tool-links.php` | Find posts missing tool links | `docs/data/blog-tool-links-audit.json` |
| `audit-blog-industry-links.php` | Find posts missing industry links | `docs/data/blog-industry-links-audit.json` |
| `suggest-new-links.php` | Suggest links across all posts | `docs/data/blog-new-link-suggestions.json` |
| `suggest-contextual-links.php` | Per-post tool/industry suggestions | `docs/content/blog/posts/{cat}/{slug}/data/suggested-contextual-links.json` |
| `suggest-ordio-feature.php` | Product + tool + industry suggestions | Console output |
| `validate-internal-links-exist.php` | Validate all internal links point to existing pages | Console output (exit code 0 = valid, 1 = broken) |

## Process for New Posts

1. **Before content:** Review `blog-tool-mapping.json` and `blog-industry-mapping.json` for topics you'll cover.
2. **After content draft:** Run `suggest-contextual-links.php` and `suggest-ordio-feature.php`.
3. **Review output:** Add 1–2 tool links when content discusses calculable topics; add 1 industry link when content mentions branches.
4. **Apply links:** Use `update-post-content.php` to add links to content HTML.
5. **Validate links exist:** Run `validate-internal-links-exist.php` to ensure all internal links point to existing pages.
6. **Validate:** Run `validate-new-post.php` (warns on tool/industry keyword gaps).

## Process for Existing Posts

1. **Run audits:**
   ```bash
   php v2/scripts/blog/audit-blog-tool-links.php [--suggest-placements]
   php v2/scripts/blog/audit-blog-industry-links.php
   ```
2. **Review audit output:** Identify posts with missing opportunities.
3. **Apply links:** Edit content HTML, then apply via `update-post-content.php --backup`.
4. **Validate links exist:** Run `validate-internal-links-exist.php` to ensure all internal links point to existing pages.
5. **Re-run audits** to verify gaps are closed.

## When to Add Links

- **TVöD, öffentlicher Dienst, SuE** → `/tools/tvoed-sue-gehaltsrechner`
- **Zuschläge, Nachtarbeit, Feiertagsarbeit** → `/tools/zuschlagsrechner`
- **Einzelhandel, Gastronomie, DEHOGA, Baugewerbe** → `/branchen/{slug}` per `blog-industry-mapping.json`

## Related Documentation

- [INTERNAL_LINKING_GUIDE](guides/INTERNAL_LINKING_GUIDE.md)
- [NEW_POST_LINKING_CHECKLIST](NEW_POST_LINKING_CHECKLIST.md)
- [BLOG_CONTENT_EDIT_WORKFLOW](BLOG_CONTENT_EDIT_WORKFLOW.md)