# New Post Linking Checklist

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

Use this checklist when adding new blog posts to ensure proper internal linking.

**See Also:** [INTERNAL_LINKING_WORKFLOW_2026.md](INTERNAL_LINKING_WORKFLOW_2026.md) for complete workflow integration.

## Pre-Publication Checklist

### 1. Identify Content Cluster

- [ ] Determine primary cluster (dienstplan, zeiterfassung, compliance, etc.)
- [ ] Identify secondary clusters if applicable
- [ ] Map to relevant topics

### 2. Pillar Page Links

- [ ] Add link to relevant pillar page (`/insights/dienstplan` or `/insights/zeiterfassung`)
- [ ] Place in first mention or introduction
- [ ] Use natural anchor text (e.g., "Dienstplan" or "mehr zum Dienstplan")

### 3. Product Page Links

- [ ] Identify relevant product pages based on cluster
- [ ] Add 1-3 product page links
- [ ] Place in solution sections or CTAs
- [ ] Use descriptive anchor text (e.g., "Schichtplanung mit Ordio")

### 4. Related Blog Posts

- [ ] Add 2-5 links to related blog posts
- [ ] Use `related_posts` field in JSON
- [ ] Ensure semantic relevance
  - [ ] **Lexikon 1:1 (Mandatory):** For each topic mentioned that has a dedicated lexikon post, add a link on first meaningful mention. Run `audit-blog-lexikon-links.php --suggest-placements` to find gaps. Check `docs/data/blog-lexikon-mapping.json` for available posts.

### 5. Tools Pages

- [ ] Check `docs/data/blog-tool-mapping.json` for topic matches (TVöD, Zuschläge, Industrieminuten, etc.)
- [ ] Add links to relevant tools when mentioned
- [ ] Use natural anchor text (e.g., "Arbeitszeitrechner")
- [ ] Place in calculation examples or how-to sections

### 6. Industry Pages

- [ ] Check `docs/data/blog-industry-mapping.json` for industry mentions (Einzelhandel, Gastronomie, etc.)
- [ ] Add 1 industry link when content mentions specific branches

### 7. Templates/Downloads

- [ ] Add links to relevant templates or downloads
- [ ] Use descriptive anchor text (e.g., "kostenlose Dienstplan Vorlage")
- [ ] Place in resource sections

### 8. FAQ Links

- [ ] Review FAQ answers
- [ ] Add internal links where relevant
- [ ] Ensure natural anchor text

### 9. Linking Scripts (MANDATORY - After Content Draft)

**Step 9.1: Generate Suggestions**
- [ ] Run `php v2/scripts/blog/suggest-contextual-links.php --post={slug} --category={category}` (generates `data/suggested-contextual-links.json`)
- [ ] Run `php v2/scripts/blog/suggest-ordio-feature.php --post={slug} --category={category}` (product/tool/industry suggestions)

**Step 9.2: Review Suggestions**
- [ ] Review `data/suggested-contextual-links.json`:
  - **Lexikon links (mandatory):** Add on first meaningful mention. Every mentioned term with a lexikon post must be linked.
  - **Industry links:** Add when industry mentioned (1 link per industry)
  - **Tool links:** Add when calculable topic discussed (1-2 links max)
  - **Template/Download links:** Add when template or download topic mentioned
- [ ] Review product suggestions from `suggest-ordio-feature.php`:
  - Match feature to content topic (see `ordio-promotion-contextual.mdc`)
  - Add 1-2 product links contextually

**Step 9.3: Apply Links**
- [ ] Edit `content-draft.html` directly
- [ ] Add links where topics naturally appear (not forced)
- [ ] Use natural anchor text (topic name, not generic phrases)
- [ ] Respect word boundaries (no partial-word links)
- [ ] Sync to JSON: `php v2/scripts/blog/update-post-content.php --post={slug} --category={category} --html=docs/content/blog/posts/{category}/{slug}/content-draft.html`

**Step 9.4: Validate (Before Publishing)**
- [ ] Run `php v2/scripts/blog/audit-blog-lexikon-links.php --post={slug} --category={category} [--suggest-placements]` – fix any missing lexikon links
- [ ] Run `php v2/scripts/blog/audit-blog-tool-links.php --post={slug} --category={category} [--suggest-placements]`
- [ ] Run `php v2/scripts/blog/audit-blog-industry-links.php --post={slug} --category={category}`
- [ ] Run `php v2/scripts/blog/audit-internal-link-density.php --post={slug} --category={category}` – verify link count meets word-count target
- [ ] Fix any validation failures before publishing

**Step 9.5: When creating new lexikon post** – Run `php v2/scripts/blog/suggest-bidirectional-links-for-new-post.php --post={slug} --category=lexikon` to find existing posts that mention the new post's topic and add in-content links to the new post.

### 10. Quality Checks

- [ ] Verify all anchor text is descriptive
- [ ] Check that anchor text is varied (avoid repeating same anchor >3 times)
- [ ] Ensure links are contextually relevant
- [ ] Verify no broken links
- [ ] Check link frequency (not excessive)
- [ ] Verify compound words are linked correctly (e.g., "Schichtplanungsfunktionen" not "Schichtplanung")
- [ ] Verify plural forms are linked correctly (e.g., "Checklisten" not "Checkliste")

### 11. Update internal_links Field

- [ ] Add all links to `internal_links` array in JSON
- [ ] Include normalized_url, anchor_text, target_type
- [ ] Add reasoning for each link

## Post-Publication

- [ ] Run link validation script
- [ ] Check carousel displays correctly
- [ ] Verify links work on live site
- [ ] Monitor for any issues

## Quick Reference

### Cluster-to-Pillar Mapping

- **dienstplan** → `/insights/dienstplan`
- **zeiterfassung** → `/insights/zeiterfassung`

### Cluster-to-Product Mapping

- **dienstplan** → `/schichtplan`
- **zeiterfassung** → `/arbeitszeiterfassung`
- **lohnabrechnung** → `/payroll`
- **compliance** → `/payroll`, `/arbeitszeiterfassung`

### Common Anchor Text Patterns

- Pillar: "Dienstplan", "mehr zum Dienstplan"
- Product: "Schichtplanung mit Ordio", "Zeiterfassungssoftware"
- Tools: "Arbeitszeitrechner", "kostenloser Urlaubsrechner"
- Templates: "kostenlose Dienstplan Vorlage"

## Related Documentation

- [INTERNAL_LINKING_WORKFLOW_2026.md](INTERNAL_LINKING_WORKFLOW_2026.md) - Complete workflow integration
- [INTERNAL_LINKING_GUIDE.md](guides/INTERNAL_LINKING_GUIDE.md) - Complete guide with examples
- [INTERNAL_LINKING_PROCESS.md](INTERNAL_LINKING_PROCESS.md) - Process overview
- [Anchor Text Guidelines](./ANCHOR_TEXT_GUIDELINES.md)
- [Link Placement Guide](./LINK_PLACEMENT_GUIDE.md)