# PDF Report > Generates professionally designed PDF audit reports. Activates when the user requests a PDF report, wants to export audit findings, asks for a printable report, or uses the generate-pdf or export-html commands. Produces a visually stunning HTML report with SVG gauge charts, color-coded severity cards, and professional tables, then converts to PDF. Uses Python script for reliable multi-engine PDF generation. All files saved to {REPORTS_DIR}/. - Skill: `mshahiddigital/pdf-report` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add mshahiddigital/pdf-report` - Raw SKILL.md: https://api.skillmd.com/api/skills/mshahiddigital/pdf-report/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: mshahiddigital (https://skillmd.com/u/mshahiddigital) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mshahiddigital/pdf-report --- # PDF Report Generation System ## Executive Summary The PDF report is the client-facing deliverable — the tangible output of the entire 21-phase audit. Report quality directly impacts perceived value. A well-designed PDF report converts audit findings into client trust: 87% of clients who receive a visually professional audit report retain the agency vs. 34% who receive a plain text output (AgencyAnalytics survey, 2024). Every phase must produce its own PDF; the final master report compiles all phases into a single document. **2025–2026 reporting context:** - Include SEO Health Index = (LOCAL-IMPACT × 0.55) + (SERP-TRUST × 0.45) as the master metric - AI Overviews impact must be called out per relevant finding (20–35% of local queries) - All CWV thresholds use 2025 values: INP < 200ms (not FID), LCP < 2.5s, CLS < 0.1 - Score grades: A (90–100) / B (75–89) / C (60–74) / D (45–59) / F (< 45) - Source data for reports comes from: Ahrefs (backlinks, keywords), SEMrush (traffic, gaps), Screaming Frog (technical crawl), Google Search Console (GSC) (coverage, performance), PageSpeed Insights + Lighthouse (CWV), BrightLocal (citations, GBP rank), Majestic (TF:CF), Google Business Profile (GBP), ChatGPT/Perplexity (AI visibility tests) - GBP 2025 features to include in reports: Q&A section completeness, service menu with prices, review velocity (last 90 days), Google Reserve/Booking integration, AI Overview local pack eligibility (≥4.3 stars, 50+ reviews), GBP Posts frequency - AI crawler access status must be reported in technical findings (14 crawlers, 3 tiers) - llms.txt presence/absence should be flagged in AI SEO section - Brand mention authority score (YouTube/Reddit/Wikipedia correlation with AI citations) in reputation section - Platform-specific AI optimization status (AIO, ChatGPT, Perplexity, Gemini, Copilot) in AI SEO section **Numbered Action Steps:** 1. Confirm `{AUDIT_DIR}/` has all required phase `.md` files — run `python3 scripts/audit_status.py --project projects/[slug]` — Effort: 1 min 2. Run `python3 scripts/report_compiler.py --project projects/[slug]` → generates `{AUDIT_DIR}/master-report.md` — Effort: 2 min 3. Build HTML report for each phase — use full design system (SVG gauges, color cards, tables) — Effort: 30–60 min per phase 4. Save HTML to `{REPORTS_DIR}/phase-[N]-[slug].html` — Effort: 1 min per phase 5. Run `python3 scripts/generate_pdf.py --html {REPORTS_DIR}/phase-[N]-[slug].html` — generates PDF — Effort: 30 sec per phase 6. Confirm PDF size and page count — alert if <2 pages (likely rendering error) or >30 pages (likely runaway content) — Effort: 1 min 7. Repeat steps 3–6 for all 21 phases + LOCAL-IMPACT + SERP-TRUST + master report — Effort: varies 8. Deliver master-report.pdf + all phase PDFs in `{REPORTS_DIR}/` folder to client — Effort: 5 min --- ## Tools for This Phase | Tool | Purpose | Cost | |---|---|---| | `python3 scripts/generate_pdf.py` | Chrome headless + WeasyPrint fallback PDF generation | Free (local) | | **Google Chrome headless** | Primary PDF engine — highest fidelity HTML→PDF | Free | | **WeasyPrint** | Fallback PDF engine — no Chrome needed | Free | | **Google Chrome browser** | Preview HTML before PDF conversion | Free | | `python3 scripts/report_compiler.py` | Compile all phase .md files into master-report.md | Free (local) | --- ## Report Quality Standards (2025) | Report Element | Minimum Standard | Excellent Standard | |---|---|---| | Cover page | Business name, score, date, URL | + SVG gauge chart, grade badge, key verdict | | Dashboard page | Score cards per dimension | + Competitor comparison bars, trend arrows | | Issue cards | Status + issue + fix | + Priority score, effort estimate, competitor context | | Priority matrix | Impact × Feasibility table | + Visual heat map, 30/90-day roadmap | | File size | < 5MB | < 2MB (optimized images) | | Page count | 15–30 pages | 20–40 pages (comprehensive) | | Completeness | All completed phases | All 21 phases + both scoring frameworks | --- ## Required Report Sections by Report Type | Report Type | Cover Page | Score Gauge | Issue Cards | Priority Matrix | Competitor Table | Quick Wins | Roadmap | AI Visibility Callout | |---|---|---|---|---|---|---|---|---| | Per-phase PDF | Yes | Yes (phase score) | Yes | Yes | Yes (phase-specific) | Yes (top 3) | No | Yes (if content/on-page/AI phase) | | LOCAL-IMPACT PDF | Yes | Yes (composite) | No | No | Yes (benchmarks) | Yes (top 5) | No | Yes (AI readiness dimension) | | SERP-TRUST PDF | Yes | Yes (composite) | No | No | Yes (benchmarks) | Yes (top 5) | No | Yes (T2 dimension) | | Master Report PDF | Yes | Yes (SEO Health Index) | Yes (all phases) | Yes (master) | Yes (full competitor summary) | Yes (top 10) | Yes (30/90/180-day) | Yes (dedicated section) | ## 2025–2026 Report Content Requirements | Section | What to Include | Why It Matters | |---|---|---| | AI Visibility Dashboard | AIO citation status, ChatGPT/Perplexity mentions, AI crawler access score | AI search drives 20–35% of local queries; clients need to see their AI presence | | GBP Health Summary | Q&A completeness, review velocity (last 90 days), service menu, Google Reserve status, AI Overview eligibility | GBP is the #1 local ranking factor; 2025 features (Q&A, service menu) directly affect AIO inclusion | | Brand Mention Authority | YouTube/Reddit/Wikipedia presence, brand mention score vs. backlink profile | Brand mentions correlate 3× more with AI visibility than backlinks (Ahrefs Dec 2025) | | AI Crawler Access | Tier 1/2/3 crawler status, llms.txt presence, IndexNow status | Blocked AI crawlers = invisible to that platform regardless of content quality | | Platform Readiness | Per-platform scores (AIO, ChatGPT, Perplexity, Gemini, Copilot) | Only 11% of domains cited by both ChatGPT and AIO — platform-specific optimization required | | Citability Score | Answer block quality, self-containment, statistical density | AI models cite passages meeting specific structural criteria (134–167 word blocks, answer-first) | ## Architecture 1. **Read** `{AUDIT_DIR}/intake-data.md` to get PROJECT_DIR, business name, URL 2. **Aggregate** all audit findings from `{AUDIT_DIR}/*.md` files 3. **Generate** a complete HTML file using the design system below with real audit data 4. **Write** the HTML file to `{REPORTS_DIR}/phase-[N]-[slug].html` 5. **Convert** to PDF using the Python script (auto-detects Chrome or WeasyPrint): ```bash python3 scripts/generate_pdf.py --html {REPORTS_DIR}/phase-[N]-[slug].html ``` Or directly via Chrome: ```bash "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \ --headless=new --disable-gpu --no-sandbox --print-to-pdf-no-header \ --print-to-pdf="{REPORTS_DIR}/phase-[N]-[slug].pdf" \ "file:///[absolute-path-to-html]" ``` 6. **Report** PDF path + file size to user ## Step 1: Detect Chrome Path (Manual Fallback) If not using the Python script, detect the Chrome binary: ```bash if [ -f "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" ]; then CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" elif command -v google-chrome &> /dev/null; then CHROME="google-chrome" elif command -v chromium-browser &> /dev/null; then CHROME="chromium-browser" elif command -v chromium &> /dev/null; then CHROME="chromium" else echo "ERROR: Chrome not found. Install with: brew install --cask google-chrome" exit 1 fi echo "Chrome found at: $CHROME" ``` ## Step 2: Generate HTML Report Write a complete HTML file using the template structure and design system below. Replace ALL placeholder values with real audit data from the conversation. ### File Naming Convention ``` reports/{business-name-slug}-seo-audit-{YYYY-MM-DD}.html reports/{business-name-slug}-seo-audit-{YYYY-MM-DD}.pdf ``` ## Step 3: Convert to PDF ```bash mkdir -p reports "$CHROME" --headless --disable-gpu --no-sandbox \ --print-to-pdf="reports/{filename}.pdf" \ "file://{absolute-path-to-html}" ``` --- ## HTML TEMPLATE STRUCTURE Generate the COMPLETE HTML below, populated with real audit data. ```html SEO Audit Report — {BUSINESS_NAME} ``` ### SECTION 1: COVER PAGE ```html
Local SEO Audit Report

{BUSINESS_NAME}

{WEBSITE_URL}

{OVERALL_SCORE} OVERALL SCORE
Prepared: {DATE}
Location: {TARGET_LOCATION}
Auditor: Local SEO Audit System v1.0
``` ### SECTION 2: TABLE OF CONTENTS ```html

Table of Contents

``` ### SECTION 3: EXECUTIVE SUMMARY ```html

01 — Executive Summary

{BUSINESS_NAME} • {WEBSITE_URL} • {DATE}

{EXECUTIVE_SUMMARY_PARAGRAPH_1}

{EXECUTIVE_SUMMARY_PARAGRAPH_2}

{EXECUTIVE_SUMMARY_PARAGRAPH_3}

Critical Issues Found: {CRITICAL_COUNT} {CRITICAL_SUMMARY_SENTENCE}
High Priority Items: {HIGH_COUNT} {HIGH_SUMMARY_SENTENCE}
Quick Wins Available: {QUICKWIN_COUNT} {QUICKWIN_SUMMARY_SENTENCE}
Strengths Identified: {STRENGTHS_COUNT} {STRENGTHS_SUMMARY_SENTENCE}
``` ### SECTION 4: SCORE DASHBOARD ```html

02 — Score Dashboard

Performance across all audit dimensions
{OVERALL_SCORE} OVERALL
Overall Health Score
{SUB_SCORE} /100
{SUB_SCORE_LABEL}
``` ### SECTION 4B: PROPRIETARY FRAMEWORK DASHBOARD ```html

02B — Proprietary Framework Scores

LOCAL-IMPACT & SERP-TRUST Assessment
SEO Health Index
{SEO_HEALTH_INDEX} Grade: {SEO_HEALTH_GRADE}
LOCAL-IMPACT (55%) + SERP-TRUST (45%)
LOCAL-IMPACT
60-Item Local Presence Assessment
{LOCAL_IMPACT_SCORE} Grade: {LOCAL_IMPACT_GRADE}
SERP-TRUST
50-Item Search Trust Assessment
{SERP_TRUST_SCORE} Grade: {SERP_TRUST_GRADE}

LOCAL-IMPACT Dimensions

{DIMENSION_NAME}
{DIMENSION_SCORE}/{DIMENSION_MAX}

SERP-TRUST Dimensions

{DIMENSION_NAME}
{DIMENSION_SCORE}/{DIMENSION_MAX}

Veto Checks

LOCAL-IMPACT Vetoes

{VETO_DESCRIPTION}

SERP-TRUST Vetoes

{VETO_DESCRIPTION}

Competitor Framework Comparison

Framework {BUSINESS_NAME} {COMP_1} {COMP_2} {COMP_3}
LOCAL-IMPACT {SCORE} {SCORE} {SCORE} {SCORE}
SERP-TRUST {SCORE} {SCORE} {SCORE} {SCORE}
SEO Health Index {SCORE} {SCORE} {SCORE} {SCORE}
``` ### SECTION 5: CRITICAL ISSUES ```html

03 — Critical Issues

Fix these immediately — they are blocking your SEO performance
{ISSUE_TITLE}
{ISSUE_DESCRIPTION_AND_FIX_STEPS}
Critical {EFFORT_ESTIMATE} {AUDIT_PHASE}

High Priority Issues

``` ### SECTION 6: PRIORITY MATRIX ```html

04 — Priority Matrix

Impact vs Effort — focus on the top-left quadrant first

High Impact / Low Effort (Do First)

  • {ITEM}

High Impact / High Effort (Plan & Schedule)

  • {ITEM}

Low Impact / Low Effort (Fill In Gaps)

  • {ITEM}

Low Impact / High Effort (Deprioritize)

  • {ITEM}
``` ### SECTION 7: QUICK WINS ```html

05 — Quick Wins

High-impact fixes you can implement today
{N}
{WIN_TITLE}

{WIN_DESCRIPTION_AND_STEPS}

``` ### SECTION 8: COMPETITOR SUMMARY ```html

06 — Competitor Summary

How you compare to your top competitors
…(truncated)