# New Tool Linking Checklist

**Last Updated:** 2026-03-25

Use this checklist when publishing a new tool to ensure proper internal linking. Parallel to [NEW_POST_LINKING_CHECKLIST.md](../blog/NEW_POST_LINKING_CHECKLIST.md).

**Full ship list (OG, carousel, registry):** [_templates/NEW_TOOL_PUBLICATION_TODO.md](../_templates/NEW_TOOL_PUBLICATION_TODO.md) · [WEBSITE_PAGE_PUBLICATION_INDEX.md](../WEBSITE_PAGE_PUBLICATION_INDEX.md)

## Pre-Publication Checklist

### 1. Data and Mapping Updates

- [ ] **blog-tool-mapping.json** – Add topic-to-tool mappings in `docs/data/blog-tool-mapping.json` (e.g. `"elterngeld"`, `"Elterngeld"` → `["/tools/elterngeldrechner"]`)
- [ ] **tools-internal-link-mapping.json** – Add tool to `docs/data/tools-internal-link-mapping.json` with suggested lexikon, templates, products, related tools
- [ ] **derive_topics_from_slug_for_tools** – Add slug-to-topic entries in `v2/config/blog-template-helpers.php` if slug-derived topics apply
- [ ] **extract-all-links.py** – Add tool URL to `TOOLS_PAGES` in `v2/scripts/blog/extract-all-links.py`
- [ ] **map-cluster-links.py** – Add tool to relevant cluster(s) in `v2/scripts/blog/map-cluster-links.py`
- [ ] **generate-anchor-text.py** – Add tool to tools-page anchor options in `v2/scripts/blog/generate-anchor-text.py`

### 2. Run Audits

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

### 3. Blog Post Links

- [ ] Add at least one contextual link in each piece of content (blog post, tool page, template content block, download page, FAQ answer) that meaningfully mentions the tool topic
- [ ] Add contextual links to relevant blog posts (1–2 per post when topic matches)
- [ ] Use descriptive anchor text (e.g. "kostenloser Elterngeld-Rechner")
- [ ] Add entries to `internal_links` in post JSON with `target_type: "tool"`, `normalized_url`, `anchor_text`, `reasoning`

### 4. Tools Cross-Linking

- [ ] Add reciprocal links from related tools (e.g. Brutto-Netto, Arbeitslosengeld, Minijob, Midijob)
- [ ] Ensure tool page links out to 1–2 related tools where appropriate

### 5. Templates and Downloads Audit

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

### 6. Documentation and Cursor Rules

- [ ] **blog-tool-linking.mdc** – Add row to Topic-to-Tool table in `.cursor/rules/blog-tool-linking.mdc`
- [ ] **INTERNAL_LINKING_GUIDE.md** – Add tool to Topic-to-Tool Mapping (Extended) in `docs/content/blog/guides/INTERNAL_LINKING_GUIDE.md`
- [ ] **ANCHOR_TEXT_GUIDELINES.md** – Add tool to Tools Page anchor table in `docs/content/blog/guides/ANCHOR_TEXT_GUIDELINES.md`

## Post-Publication

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

## Quick Reference

### Topic-to-Tool Mapping (Example: Elterngeld)

| Topics | Tool URL | Example Anchor |
|--------|----------|----------------|
| Elterngeld, Elternzeit, BEEG, Basiselterngeld, ElterngeldPlus | `/tools/elterngeldrechner/` | kostenloser Elterngeld-Rechner |

### 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. "kostenloser Elterngeld-Rechner"), not "click here". See [INTERNAL_LINKING_BEST_PRACTICES.md](../../systems/internal-linking/INTERNAL_LINKING_BEST_PRACTICES.md)
- **Placement:** Near top of relevant sections, first meaningful mention
- **Hub-spoke:** Tools index = hub; tool pages = spokes; blog posts link to tools when calculable topics are discussed

## Related Documentation

- [INTERNAL_LINKING_GUIDE.md](../blog/guides/INTERNAL_LINKING_GUIDE.md)
- [INTERNAL_LINKING_BEST_PRACTICES.md](../../systems/internal-linking/INTERNAL_LINKING_BEST_PRACTICES.md)
- [ANCHOR_TEXT_GUIDELINES.md](../blog/guides/ANCHOR_TEXT_GUIDELINES.md)
- [TOOLS_INVENTORY.md](TOOLS_INVENTORY.md)
- [TOOLS_CONTENT_WORKFLOW.md](../../guides/tools-pages/TOOLS_CONTENT_WORKFLOW.md)