# Internal Linking: Templates, Tools, and Download Pages

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

Workflow and scripts for internal linking from templates, tools, and download pages to lexikon, tools, templates, product pages, and related content. Aligns with [blog internal linking](INTERNAL_LINKING_BEST_PRACTICES.md).

## Overview

| Page Type | Link Approach | Mapping File | Suggestion Script | Audit Script |
|-----------|---------------|---------------|-------------------|--------------|
| Templates | Opportunity-driven; 1:1 lexikon mandatory | template-internal-link-targets.json, template-internal-link-mapping.json | suggest-template-contextual-links.php | validate-template-internal-links.php, audit-blog-template-links.php |
| Tools | Opportunity-driven; 1:1 lexikon mandatory | tools-internal-link-mapping.json | — | audit-tools-internal-links.php, audit-blog-tool-links.php |
| Downloads | Opportunity-driven; 1:1 lexikon mandatory | download-internal-link-targets.json | — | audit-download-internal-links.php, audit-blog-download-links.php |

## Mapping Files

- **template-internal-link-targets.json** – Per-template suggested targets (product, tools, related_templates, blog). Used by section briefs and validation.
- **template-internal-link-mapping.json** – Keyword-to-URL mapping for suggest script. Extends targets with lexikon/tool/product by topic.
- **tools-internal-link-mapping.json** – Per-tool suggested lexikon, templates, product, related_tools.
- **download-internal-link-targets.json** – Per-download suggested lexikon, tools, templates, product.

## Scripts

### Templates

```bash
# Suggest contextual links (run after content draft)
php v2/scripts/templates/suggest-template-contextual-links.php --template=id
php v2/scripts/templates/suggest-template-contextual-links.php --all

# Validate min 3 links, canonical URLs
php v2/scripts/templates/validate-template-internal-links.php --template=id
php v2/scripts/templates/validate-template-internal-links.php --all

# Suggest placements for templates with gaps
php v2/scripts/templates/validate-template-internal-links.php --all --suggest-placements
```

Output: `docs/systems/templates/template-data/{id}/data/suggested-contextual-links.json`

### Tools

```bash
php v2/scripts/tools/audit-tools-internal-links.php [--tool=slug]
```

Output: `docs/data/tools-internal-links-audit.json`

### Downloads

```bash
php v2/scripts/audit-download-internal-links.php [--download=slug]
```

Output: `docs/data/download-internal-links-audit.json`

### Blog-to-Template and Blog-to-Download Audits

```bash
# Find blog posts missing template links (after adding new template to blog-template-mapping)
php v2/scripts/blog/audit-blog-template-links.php [--suggest-placements]
```

Output: `docs/data/blog-template-links-audit.json`

```bash
# Find blog posts missing download links (after adding new download to blog-template-mapping)
php v2/scripts/blog/audit-blog-download-links.php [--suggest-placements]
```

Output: `docs/data/blog-download-links-audit.json`

### Find Content Mentioning Topic (Helper)

When creating a new tool, template, or download, use this script to find existing content that mentions the topic and may need a link:

```bash
php v2/scripts/internal-linking/find-content-mentioning-topic.php --topic=TOPIC [--resource-type=tool|template|download] [--output=path]
```

Output: JSON with file paths, line numbers, and snippets. Use as alternative to manual `grep` when adding cross-resource links.

### Baseline Extraction

```bash
python3 v2/scripts/internal-linking/extract-internal-links-from-pages.py
```

Output: `docs/systems/internal-linking/CURRENT_LINK_AUDIT_*.json`

## Workflow

### New Template

1. Add template to template-internal-link-targets.json (product, tools, related_templates, blog)
2. Add template to template-internal-link-mapping.json (lexikon, tools, product, related_templates)
3. Add template to blog-template-mapping.json templates section (topic keywords → `/vorlagen/{slug}`)
4. Run `audit-blog-template-links.php --suggest-placements`; review `blog-template-links-audit.json` for posts missing the template link
5. After content draft: run `suggest-template-contextual-links.php --template=id`
6. Review suggestions, add links in content.md, sync to content-blocks.json
7. Add 1-2 contextual links in template-faqs.json where FAQs mention calculable topics
8. Validate: `validate-template-internal-links.php --template=id`

**Checklist:** [NEW_TEMPLATE_LINKING_CHECKLIST.md](../templates/NEW_TEMPLATE_LINKING_CHECKLIST.md)

### New Tool

1. Add tool to tools-internal-link-mapping.json (lexikon, templates, product, related_tools)
2. Add tool to blog-tool-mapping.json (for blog-to-tool linking)
3. Run `audit-blog-tool-links.php --suggest-placements`; review `blog-tool-links-audit.json`
4. Add contextually relevant links from mapping (1:1 lexikon terms mandatory; never force links to hit a count)
5. Run `audit-tools-internal-links.php` to verify

**Checklist:** [NEW_TOOL_LINKING_CHECKLIST.md](../../content/tools/NEW_TOOL_LINKING_CHECKLIST.md)

### New Download

1. Add download to download-internal-link-targets.json
2. Add download to blog-template-mapping.json downloads section (for blog-to-download linking)
3. Run `audit-blog-download-links.php --suggest-placements`; review `blog-download-links-audit.json`
4. Add contextually relevant links from mapping (1:1 lexikon terms mandatory; never force links to hit a count)
5. Run `audit-download-internal-links.php` to verify

**Checklist:** [NEW_DOWNLOAD_LINKING_CHECKLIST.md](../../content/pages/download-pages/NEW_DOWNLOAD_LINKING_CHECKLIST.md)

## Validation Checklist

- [ ] Templates: `validate-template-internal-links.php --all` passes
- [ ] Tools: `audit-tools-internal-links.php` – review below_min_list
- [ ] Downloads: `audit-download-internal-links.php` – review below_min_list
- [ ] Canonical URLs only (no /zeiterfassung, use /arbeitszeiterfassung; no /templates/, use /vorlagen/)
- [ ] Natural anchor text (no "click here", "hier", "mehr erfahren")

## Anchor Text Guidelines

- Use natural, contextual phrases from the content
- Match topic: "Arbeitszeitrechner", "Minijob-Rechner", "Ordio Zeiterfassung"
- Avoid generic: "hier", "mehr erfahren", "weitere Informationen"
- See [INTERNAL_LINKING_BEST_PRACTICES.md](INTERNAL_LINKING_BEST_PRACTICES.md)

## Related Documentation

- [INTERNAL_LINKING_BEST_PRACTICES.md](INTERNAL_LINKING_BEST_PRACTICES.md)
- [INTERNAL_LINKING_WORKFLOW_2026.md](../../content/blog/INTERNAL_LINKING_WORKFLOW_2026.md)
- [CANONICAL_URLS_AND_LINKING.md](../../development/CANONICAL_URLS_AND_LINKING.md)
- [GAP_ANALYSIS.md](GAP_ANALYSIS.md)