` length (warn; **`--strict`** → exit 1 on warns). - `validate-aeo-capsule-diversity.php` — Flags overuse of the **„In Kürze:“** template label (warn by default; **`--strict`** in `blog-post-validate-strict`). See [CONTENT_DEPTH_GUIDELINES.md](CONTENT_DEPTH_GUIDELINES.md) (AEO capsules without repetitive labels). - `validate-geo-citability.php` — Definition signal, Fazit H2, FAQ count (lexikon/ratgeber). **`--strict`** fails on warnings too. - `audit-blog-repetitive-phrasing.py` — Scans all `v2/data/blog/posts/**/*.json` for label fatigue + soft AI-tell phrases; optional `--csv=path`, `--include-drafts`, `--fail-on high|medium`. **Makefile:** `make blog-outline-gate POST=slug CAT=lexikon`, `make blog-post-validate POST=slug CAT=lexikon`, **`make blog-post-validate-strict`**, and **`make audit-blog-repetition`** — see repo `Makefile`. **Skyscraper / competitive ratio:** there is no separate `make blog-skyscraper-*` target—`blog-post-validate` already includes `compare-content-to-competitors` + `validate-content-completeness`; use **`blog-post-validate-strict`** for `compare-content --strict`. See [CI_BLOG_CONTENT_GUARDRAILS.md](CI_BLOG_CONTENT_GUARDRAILS.md). ### Quality Checks - `weekly-quality-check.php` - Weekly quality audits (FAQ, links, schema, freshness) - `audit-faq-quality.php` - FAQ quality audit - `analyze-link-quality.php` - Link quality analysis - `validate-link-quality.php` - Validate link quality ### Keyword workflow (SISTRIX / targets) - `collect-post-keywords-sistrix.php` — SISTRIX metrics + ideas → `keywords-sistrix.json`. Use `--primary-only` before finalizing secondaries in `target-keywords.json`. See [KEYWORD_RESEARCH_WORKFLOW.md](KEYWORD_RESEARCH_WORKFLOW.md). - `propose-secondary-keywords.php` — Rank secondary keywords from existing `keywords-sistrix.json` (optional `--write` to merge into `target-keywords.json`). - `derive-target-keywords.php` — Primary/secondary from GSC; use `--from-sistrix` when `performance-gsc.json` is missing. - `validate-keyword-decision.php` — Validates `KEYWORD_DECISION.md` (warnings; `--strict` for CI-style failure). ### Data Collection - `collect-post-performance-ga4.php` - Collect GA4 data for posts - `collect-post-performance-gsc.php` - Collect GSC data for posts - `pull-sistrix-data.php` - Collect SISTRIX data - `run-all-data-collection.php` - Run all data collection scripts - `weekly-priority-refresh.php` - Weekly priority refresh (GA4/GSC updates) ### Content Edit - `update-post-content.php` - Canonical script for updating blog post content; replaces `content.html`, regenerates `content.text` and `word_count` - `fix-blog-table-styling.php` - Strip Tailwind from post tables, wrap in `table-breakout-wrapper`, restore Ordio blue header styling. `--post=` + `--category=` or `--all [--backup]`. See [BLOG_TABLE_FORMAT.md](BLOG_TABLE_FORMAT.md); `validate-new-post.php` warns on noncompliant tables. - `apply-and-validate-post.sh` - Runs `update-post-content.php` then `make blog-post-validate` (or **`--strict`** → `blog-post-validate-strict`). Example: `./v2/scripts/blog/apply-and-validate-post.sh --post=slug --category=lexikon --html=docs/content/blog/posts/lexikon/slug/content-draft.html` - `sync-post-content-text.php` - Regenerate `content.text` and `word_count` from existing `content.html` (when HTML was edited outside update-post-content.php) **Usage:** See [BLOG_CONTENT_EDIT_WORKFLOW.md](BLOG_CONTENT_EDIT_WORKFLOW.md). Never edit post JSON directly. Use **one** tracked `content-draft.html` per post; avoid `*-expanded` / `*-improved` filenames in git ([CONTENT_DRAFT_LEGACY_INVENTORY.md](CONTENT_DRAFT_LEGACY_INVENTORY.md)). **Makefile shortcuts (ergonomics):** [BLOG_WORKFLOW_EFFICIENCY.md](BLOG_WORKFLOW_EFFICIENCY.md) — `make blog-apply-validate` / `blog-apply-validate-strict` with `POST`, `CAT`, `HTML=` path; `make blog-post-validate-faq` when only FAQs changed. ### FAQ Management - `add-faqs-to-post.php` - Add FAQs to blog post (updates `faqs` array only, sorts by logical flow by default) - `audit-faq-source-drift.php` - Read-only compare post `faqs` vs `data/faq-answers-optimized.json` - `reorder-faqs-by-logical-flow.php` - Reorder existing FAQs by logical flow (definition first, then how-to, etc.) - `remove-faqs-from-content.php` - Remove FAQ sections from `content.html` (cleanup script) - `generate-faq-questions.php` - Generate FAQ questions - `generate-faq-answers-ai.php` - Generate FAQ answers using AI - `add-faq-links.php` - Add internal links to FAQ answers - `automate-faq-enhancement.php` - Automate FAQ enhancement - `expand-short-faq-answers.php` - Expand short FAQ answers - `condense-faq-answers.php` - Condense long FAQ answers - `prioritize-faq-improvements.php` - Prioritize FAQ improvements **FAQ pipeline vs published JSON:** What visitors and schema use is **`faqs` in** `v2/data/blog/posts/{category}/{slug}.json`. Under `docs/content/blog/posts/.../data/`, the files `faq-research.json` → `faq-questions.json` → `faq-answers-optimized.json` are **pipeline stages**—do not maintain them as three independent “sources of truth.” After substantive FAQ work, run `validate-faq-quality.php` and optionally **`audit-faq-source-drift.php`** (read-only compare of post `faqs` vs `faq-answers-optimized.json`). Full model: [FAQ_SOURCE_OF_TRUTH.md](FAQ_SOURCE_OF_TRUTH.md). ### Link Management - `add-bidirectional-links.php` - Add bidirectional in-content links (config-driven) - `add-links-to-json.php` - Add internal links to posts - `add-pillar-links.php` - Add pillar page links - `add-tools-links.php` - Add tools page links - `remove-stop-word-links.php` - Remove stop word links - `fix-malformed-links.php` - Fix malformed links - `suggest-new-links.php` - Suggest new internal links - `suggest-contextual-links.php` - Per-post tool/industry/lexikon suggestions (output: data/suggested-contextual-links.json); use `--all` to audit all pre-existing posts - `generate-blog-lexikon-mapping.php` - Regenerate topic-to-lexikon mapping (run after adding new lexikon posts) - `audit-blog-tool-links.php` - Audit tool link gaps - `audit-blog-industry-links.php` - Audit industry link gaps - `audit-blog-lexikon-links.php` - Audit lexikon-to-lexikon link gaps - `add-contextual-links-from-suggestions.php` - Add suggested links in bulk (run suggest-contextual-links --all first) ### Content Analysis - `analyze-post-seo.php` - Analyze post SEO - `analyze-post-content.php` - Analyze post content - `analyze-post-links.php` - Analyze post links - `analyze-cluster-relationships.php` - Analyze cluster relationships ### Priority & Reporting - `calculate-comprehensive-priority.php` - Calculate post priority scores - `generate-priority-dashboard.php` - Generate priority dashboard - `generate-review-priority-list.php` - Generate review priority list - `generate-automated-reports.php` - Generate automated reports ### Validation - `validate-post-dates.php` - Validate post dates - `validate-faq-schema.php` - Validate FAQ schema - `validate-link-quality.php` - Validate link quality - `validate-seo-meta.php` - Validate SEO meta tags - `validate-content-integrity.php` - Validate content integrity ## Detailed Script Documentation ### Weekly Quality Check **File:** `weekly-quality-check.php` **Purpose:** Automates weekly quality checks for blog posts **Usage:** ```bash php v2/scripts/blog/weekly-quality-check.php [--email] ``` **What it does:** - Audits FAQ quality - Checks link health - Validates schema - Checks content freshness **Output:** Report saved to `docs/content/blog/reports/weekly-quality-check-YYYY-MM-DD.md` **Dependencies:** - `audit-faq-quality.php` - `analyze-link-quality.php` - `blog-template-helpers.php` --- ### Weekly Priority Refresh **File:** `weekly-priority-refresh.php` **Purpose:** Updates GA4/GSC data and recalculates priority scores **Usage:** ```bash php v2/scripts/blog/weekly-priority-refresh.php [--limit=N] [--dry-run] ``` **What it does:** - Updates GA4 data - Updates GSC data - Recalculates priority scores - Generates priority report **Dependencies:** - `collect-post-performance-ga4.php` - `collect-post-performance-gsc.php` - `calculate-comprehensive-priority.php` --- ### Link Quality Analysis **File:** `analyze-link-quality.php` **Purpose:** Analyzes anchor text quality and link relevance **Usage:** ```bash php v2/scripts/blog/analyze-link-quality.php [--output=report.md] ``` **What it does:** - Extracts all links from posts - Checks for stop words in anchor text - Identifies too-short anchor text - Identifies generic anchor text - Generates quality report **Output:** Report saved to `docs/content/blog/LINK_QUALITY_ANALYSIS.md` **Dependencies:** - `blog-template-helpers.php` --- ### Update Post Content **File:** `update-post-content.php` **Purpose:** Canonical script for updating blog post content. Never edit `content.html` directly in JSON files – use this script to avoid JSON escaping, Unicode corruption, and sync issues. **Usage:** ```bash # Replace from file php v2/scripts/blog/update-post-content.php --post=slug --category=lexikon --html=path/to/content.html # Replace from stdin php v2/scripts/blog/update-post-content.php --post=slug --category=lexikon --stdin # Dry-run (validate only, no write) php v2/scripts/blog/update-post-content.php --post=slug --category=lexikon --html=... --dry-run # With backup before write php v2/scripts/blog/update-post-content.php --post=slug --category=lexikon --html=... --backup ``` **What it does:** - Loads post JSON via `json_decode()` - Replaces `content.html` with provided HTML - Regenerates `content.text` from `strip_tags(html)` - Recomputes `word_count` - Updates `modified_date` - Writes with `JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES` **See:** [BLOG_CONTENT_EDIT_WORKFLOW.md](BLOG_CONTENT_EDIT_WORKFLOW.md) --- ### Sync Post Content Text **File:** `sync-post-content-text.php` **Purpose:** Regenerate `content.text` and `word_count` from existing `content.html` without replacing HTML. Use when HTML was edited outside `update-post-content.php`. **Usage:** ```bash # Single post php v2/scripts/blog/sync-post-content-text.php --post=slug --category=lexikon # All posts php v2/scripts/blog/sync-post-content-text.php --all # Dry-run php v2/scripts/blog/sync-post-content-text.php --post=slug --category=lexikon --dry-run ``` **See:** [BLOG_CONTENT_EDIT_WORKFLOW.md](BLOG_CONTENT_EDIT_WORKFLOW.md) --- ### FAQ Quality Audit **File:** `audit-faq-quality.php` **Purpose:** Audits FAQ quality across all posts **Usage:** ```bash php v2/scripts/blog/audit-faq-quality.php ``` **What it checks:** - Answer length (too short/long) - Keyword integration - Internal links in FAQs - FAQ count per post **Output:** Report saved to `docs/content/blog/FAQ_QUALITY_AUDIT.md` --- ### GA4 Data Collection **File:** `collect-post-performance-ga4.php` **Purpose:** Collects GA4 performance data for blog posts **Usage:** ```bash php v2/scripts/blog/collect-post-performance-ga4.php [--post=slug] [--category=category] [--all] [--limit=N] [--dry-run] ``` **What it collects:** - Page views (last 90 days, last year) - Sessions - Bounce rate - Average engagement time **Dependencies:** - Google API credentials (`v2/config/google-api-credentials.php`) - Composer dependencies --- ### GSC Data Collection **File:** `collect-post-performance-gsc.php` **Purpose:** Collects Google Search Console data for blog posts **Usage:** ```bash php v2/scripts/blog/collect-post-performance-gsc.php [--post=slug] [--category=category] [--all] [--limit=N] [--dry-run] ``` **What it collects:** - Clicks - Impressions - Average position - CTR **Dependencies:** - Google API credentials (`v2/config/google-api-credentials.php`) - Composer dependencies --- ### Add Bidirectional Links **File:** `add-bidirectional-links.php` **Purpose:** Adds bidirectional in-content links to target posts. Config-driven; replaces per-post scripts (add-recruiting-links.php, add-cost-per-hire-links.php, add-mitarbeitergespraech-links.php, etc.) for standard search/replace patterns. **Usage:** ```bash php v2/scripts/blog/add-bidirectional-links.php --post=slug --category=lexikon [--dry-run] php v2/scripts/blog/add-bidirectional-links.php --post=recruiting --category=lexikon --config=/path/to/bidirectional-links.json ``` **What it does:** - Loads config from `docs/content/blog/posts/{category}/{slug}/data/bidirectional-links.json` - Applies content replacements via `update-post-content.php --backup` - Applies FAQ replacements via direct JSON edit - Skips targets where link already present **Config:** See [BIDIRECTIONAL_LINKS_CONFIG.md](BIDIRECTIONAL_LINKS_CONFIG.md). **Dependencies:** - `update-post-content.php` --- ### Add Internal Links **File:** `add-links-to-json.php` **Purpose:** Adds internal links to blog posts **Usage:** ```bash php v2/scripts/blog/add-links-to-json.php [--post=slug] [--category=category] [--all] [--dry-run] ``` **What it does:** - Detects keywords in content - Adds contextual internal links - Validates anchor text quality - Preserves existing links **Dependencies:** - `link_utils.php` - `blog-template-helpers.php` --- ### Generate FAQ Questions **File:** `generate-faq-questions.php` **Purpose:** Generates FAQ questions for blog posts **Usage:** ```bash php v2/scripts/blog/generate-faq-questions.php [--post=slug] [--category=category] [--all] ``` **What it does:** - Analyzes post content - Generates relevant FAQ questions - Saves to post JSON file **Dependencies:** - OpenAI API key (`v2/config/openai-api-key.php`) - `blog-template-helpers.php` --- ### Generate FAQ Answers (AI) **File:** `generate-faq-answers-ai.php` **Purpose:** Generates FAQ answers using AI **Usage:** ```bash php v2/scripts/blog/generate-faq-answers-ai.php [--post=slug] [--category=category] [--all] ``` **What it does:** - Generates answers for existing FAQ questions - Uses OpenAI API - Validates answer quality - Saves to post JSON file **Dependencies:** - OpenAI API key (`v2/config/openai-api-key.php`) - `blog-template-helpers.php` --- ### Add FAQs to Post **File:** `add-faqs-to-post.php` **Purpose:** Adds FAQs to a blog post JSON file (updates `faqs` array only, removes from HTML). **Sorts FAQs by logical flow by default** (definition first, then how-to, etc.). Use `--no-sort` to preserve input order. **Usage:** ```bash php v2/scripts/blog/add-faqs-to-post.php --post=slug --category=category [--faqs=faqs.json] [--replace] [--no-sort] ``` **What it does:** - Loads FAQs from `--faqs` if set; otherwise uses `docs/content/blog/posts/{category}/{slug}/data/faq-answers-optimized.json` when it exists - **Default:** merges into existing `faqs` (skips duplicate questions / strong H2 overlap); if `faqs` is empty, may extract from HTML (legacy) - **`--replace`:** replaces `faqs` with the loaded set (recommended after editing the optimized file so published JSON matches the pipeline artifact) - Updates `faqs` array in JSON - **Removes FAQ sections from HTML content** (prevents duplication) - Updates `modified_date` **Important:** FAQs are stored only in the `faqs` array, NOT in `content.html`. The template renders FAQs separately via `BlogFAQ.php` component. **Example:** ```bash php v2/scripts/blog/add-faqs-to-post.php --post=recap-webinar-sv-pruefung --category=ratgeber --faqs=/tmp/faqs.json ``` **Dependencies:** - `blog-template-helpers.php` **See:** [FAQ_SOURCE_OF_TRUTH.md](FAQ_SOURCE_OF_TRUTH.md), `docs/content/blog/FAQ_CONTENT_SEPARATION_FIX.md` --- ### Audit FAQ source drift (read-only) **File:** `audit-faq-source-drift.php` **Purpose:** Compares published `faqs` in the post JSON with `docs/content/blog/posts/{category}/{slug}/data/faq-answers-optimized.json` (when present). Normalizes questions the same way as merge logic; compares a hash of stripped answer text. **Does not modify files.** **Usage:** ```bash php v2/scripts/blog/audit-faq-source-drift.php --post=slug --category=category ``` **Exit codes:** `0` = OK or SKIP (no pipeline file); `1` = DRIFT; `2` = error. **See:** [FAQ_SOURCE_OF_TRUTH.md](FAQ_SOURCE_OF_TRUTH.md) --- ### Remove FAQs from Content HTML **File:** `remove-faqs-from-content.php` **Purpose:** Removes FAQ sections from `content.html` while preserving FAQs in `faqs` array **Usage:** ```bash # Dry run (test without modifying files) php v2/scripts/blog/remove-faqs-from-content.php --dry-run # Remove FAQs from all posts php v2/scripts/blog/remove-faqs-from-content.php # Remove FAQs from specific post php v2/scripts/blog/remove-faqs-from-content.php --post=slug --category=category ``` **What it does:** - Scans blog posts for FAQ sections in HTML - Removes FAQ headings (`