# New Download Linking Checklist

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

Use this checklist when publishing a new download page to ensure proper internal linking. Parallel to [NEW_TOOL_LINKING_CHECKLIST.md](../../tools/NEW_TOOL_LINKING_CHECKLIST.md) and [NEW_TEMPLATE_LINKING_CHECKLIST.md](../../../systems/templates/NEW_TEMPLATE_LINKING_CHECKLIST.md).

## Pre-Publication Checklist

### 1. Data and Mapping Updates

- [ ] **blog-template-mapping.json** – Add topic→download URL mappings in `docs/data/blog-template-mapping.json` downloads section (e.g. `"Lohnabrechnung"`, `"Lohnabrechnungen"` → `["/download/lohnabrechnungen-kalendermonat"]`). Include synonyms.
- [ ] **download-internal-link-targets.json** – Add entry to `docs/data/download-internal-link-targets.json` (lexikon, tools, templates, product)

### 2. Run Audits

- [ ] Run `php v2/scripts/blog/audit-blog-download-links.php --suggest-placements`
- [ ] Review `docs/data/blog-download-links-audit.json` for posts missing the download link
- [ ] Run `php v2/scripts/audit-download-internal-links.php --download={slug}`

### 3. Blog Post Links

- [ ] Add contextual links to relevant blog posts (1–2 per post when topic matches)
- [ ] Use descriptive anchor text (e.g. "Leitfaden Lohnabrechnungen")
- [ ] Add entries to `internal_links` in post JSON with `target_type: "download"`, `normalized_url`, `anchor_text`, `reasoning`

### 4. Tools and Templates Cross-Linking

- [ ] Find content mentioning the topic: `php v2/scripts/internal-linking/find-content-mentioning-topic.php --topic={topic}` (or `grep -r '{topic}' v2/pages/tools_*.php docs/systems/templates/template-data/*/content/ v2/systems/excel-template-generator/data/template-faqs.json`)
- [ ] Add at least one contextual link where topic is discussed

## Post-Publication

- [ ] Run link validation: `python3 v2/scripts/blog/validate-all-links.py` (or equivalent)
- [ ] Manual spot-check: download page, 1–2 blog posts with new links
- [ ] Verify links work and anchor text is natural

## Quick Reference

### Topic-to-Download Mapping (Example: Lohnabrechnungen)

| Topics | Download URL | Example Anchor |
|--------|--------------|----------------|
| Lohnabrechnung, Lohnabrechnungen, Kalendermonat | `/download/lohnabrechnungen-kalendermonat` | Leitfaden Lohnabrechnungen |

### Best Practices

- **1:1 lexikon terms (mandatory):** When content mentions a term with a dedicated lexikon post, add a link on first mention.
- **Contextual links:** In main content, not only navigation. Never force links to hit a count.
- **Anchor text:** Descriptive (e.g. "Onboarding-Checkliste für Gastronomie"), not "click here"
- **Placement:** Near top of relevant sections, first meaningful mention
- **Quantity:** 1–2 download links per post when topic matches; avoid over-linking
- **At least one link:** Add at least one contextual link in each piece of content (blog post, tool page, template content block, FAQ answer) that meaningfully mentions the download topic

## Related Documentation

- [TEMPLATES_TOOLS_DOWNLOADS_INTERNAL_LINKING.md](../../../systems/internal-linking/TEMPLATES_TOOLS_DOWNLOADS_INTERNAL_LINKING.md)
- [INTERNAL_LINKING_WORKFLOW_2026.md](../../blog/INTERNAL_LINKING_WORKFLOW_2026.md)
- [download-pages.mdc](../../../.cursor/rules/download-pages.mdc)