website-audit

name	website-audit
description	Audits the Deslop website for SEO, AI search performance, structured data, mobile usability, broken links, and social media cards. Fixes issues found. Use when the user mentions "audit website", "SEO", "fix search ranking", "AI search", "structured data", "social media cards", or "website performance".

Website Audit

Performs a comprehensive website audit and fixes issues affecting search visibility and AI discoverability.

The Deslop site is an Eleventy static site rooted at site/:

• Source templates: site/src/
• Eleventy config: site/eleventy.config.js
• Generated output (never edit): site/_site/
• Design system docs + mockups: docs/designs/ (see docs/designs/designsystem.md)
• Business / positioning context: AGENTS.md Project Overview + docs/specs/

Copy this checklist and track your progress:

Audit Progress:
- [ ] Step 1: Read guidelines
- [ ] Step 2: Audit AI search readiness
- [ ] Step 3: Audit SEO and keywords
- [ ] Step 4: Audit crawling and indexing
- [ ] Step 5: Audit broken links and canonicalization
- [ ] Step 6: Audit mobile usability
- [ ] Step 7: Audit structured data
- [ ] Step 8: Audit social media cards
- [ ] Step 9: Audit For Unsubstantiated Claims
- [ ] Step 10: Audit Design Compliance
- [ ] Step 11: Test with Playwright
- [ ] Step 12: Report findings

• Check the outputted HTML/CSS/JavaScript AFTER the website is generated by Eleventy. Don't just check the template source before generation.
• Fix issues at the core where the Eleventy templates live (site/src/) — never in site/_site/.
• Never manually edit the generated website content directly.
• ENSURE THE FOOTER HAS A copyright link to nimblesite.co.
• Respect the repo-wide CSS rules from AGENTS.md: ZERO duplicate CSS, hard CSS budget 1.5k LOC.

Step 1 — Read guidelines

Fetch and read each of these before auditing. These are the authoritative references for every step that follows.

• Google's guidance on using generative AI content
• Top ways to ensure content performs well in Google's AI experiences
• SEO Starter Guide

If the repo has a business plan doc, take it into account. For Deslop, use the Project Overview in AGENTS.md and the positioning material in docs/specs/ as the business context.

Identify the website source files in site/src/ and read site/eleventy.config.js so you know how templates, metadata, permalinks, and collections are wired.

Step 2 — Audit AI search readiness

Apply the guidance from the AI search article. Check:

1. Content quality — Is content original, expert-level, and comprehensive? Flag thin or duplicated pages.
2. Clear structure — Do pages use descriptive headings, lists, and concise answers to likely questions?
3. Entity clarity — Are key terms, products, and concepts defined clearly so AI can extract them? (For Deslop: "LSP server", "MCP server", "clone detection", "tree-sitter", "Type-2 clones", "ranking score" should each be defined once, prominently.)
4. Freshness signals — Are dates, update timestamps, and authorship present?

Fix issues directly in the source files under site/src/. For each fix, note what changed and why.

Step 3 — Audit SEO and keywords

1. Search Google Trends for trending keywords related to the website's content.
2. Review each page's <title>, <meta name="description">, and <h1> tags.
3. Check for keyword opportunities — can trending terms be naturally inserted into headings, descriptions, or body content?
4. Verify each page has a unique, descriptive title (50-60 chars) and meta description (150-160 chars).
5. Check image alt attributes describe the image content and include relevant keywords where natural.

Apply the SEO Starter Guide principles. Fix issues directly in the Eleventy templates.

Step 4 — Audit crawling and indexing

Reference: Overview of crawling and indexing topics

1. robots.txt — Locate and review it. Verify it doesn't block important pages. Reference: robots.txt spec
2. Sitemap — Locate the sitemap (or sitemap index). Verify all important pages are listed and no dead URLs are included. Reference: Sitemap guidelines
3. Meta robots tags — Check for unintended noindex or nofollow directives on pages that should be indexed.

Note: robots.txt and sitemaps are often auto-generated. For Eleventy, they're typically emitted from templates in site/src/ — check the generator config/template, not just the output file.

Step 5 — Audit broken links and canonicalization

Reference: What is canonicalization

1. Check all internal links resolve to valid pages (no 404s).
2. Verify <link rel="canonical"> tags are present and point to the correct URL.
3. Check for duplicate content accessible via multiple URLs (with/without trailing slash, www vs non-www).
4. Verify redirects use 301 (permanent) not 302 (temporary) where appropriate.

Step 6 — Audit mobile usability

Reference: Mobile-first indexing best practices

1. Verify the <meta name="viewport"> tag is present and correctly configured.
2. Check that content is identical between mobile and desktop (mobile-first indexing requires this).
3. Verify touch targets are adequately sized (min 48x48px).
4. Check font sizes are readable without zooming (min 16px body text).

Step 7 — Audit structured data

Reference: Structured data guidelines

1. Check for existing JSON-LD <script type="application/ld+json"> blocks.
2. Verify the structured data matches the page content (no misleading markup).
3. Add missing structured data where appropriate:
   • Organization/Person on the homepage
   • Article/BlogPosting on blog posts (with author, datePublished, dateModified)
   • BreadcrumbList for navigation
   • FAQ for pages with question/answer content
4. Validate JSON-LD syntax is correct.

Step 8 — Audit social media cards

Reference: Implementing Social Media Preview Cards

Check every page template includes:

Open Graph (Facebook/LinkedIn):

• og:title, og:description, og:image, og:url, og:type

Twitter Card:

• twitter:card, twitter:title, twitter:description, twitter:image

Verify og:image dimensions are at least 1200x630px. Fix missing or incomplete tags.

Step 9 - Audit For Unsubstantiated Claims

Ensure that all claims are backed up with a link to a reputable source. As an example, this claim isn't valid as content unless it links to an authority that found this through research

Research shows teams with strong DevEx perform 4-5x better across speed, quality, and engagement

Search for the authoritative URL and add a link to the URL. If it is not available, change the claim to something that can be substatiated.

Step 10 — Audit Design Compliance

Read the design system docs and view the design screens in docs/designs/ — specifically docs/designs/designsystem.md, docs/designs/designsystem.png, docs/designs/landing/, docs/designs/logo.svg, and docs/designs/messaging.md. Verify the rendered pages match the design system (typography scale, color palette, spacing, logo usage, tone from messaging.md).

Step 11 — Test with Playwright

Build and run the website locally. For this repo the dev server lives in site/:

cd site && npm run start   # or npm run build && open _site/index.html

Check site/package.json for the exact script names if they differ.

Desktop tests (1280x720):

1. Navigate to the homepage — take a screenshot.
2. Navigate to each major section — verify pages load without errors.
3. Check the browser console for JavaScript errors.
4. Verify all navigation links work.

Mobile tests (375x667, iPhone SE):

1. Resize the browser to mobile dimensions.
2. Navigate to the homepage — take a screenshot.
3. Verify the layout is responsive (no horizontal overflow, readable text).
4. Test navigation menu (hamburger menu if applicable).

If any page fails to load or has console errors, fix the issue (in the Eleventy source under site/src/) and retest.

Step 12 — Report findings

Summarize the audit results:

## Website Audit Report

### Fixed
- [List each issue fixed with file and line reference]

### Warnings (manual review needed)
- [Issues that need human judgment]

### Passed
- [Areas that passed audit with no issues]

### Screenshots
- [Reference Playwright screenshots taken]

Rules

• Fix issues directly — don't just report them. Only flag issues as warnings when they require human judgment (e.g., content tone, keyword selection).
• One step at a time — complete each step before moving to the next.
• Preserve existing content — improve structure and metadata without rewriting the author's voice.
• No keyword stuffing — keywords must read naturally in context.
• Respect the framework — edit Eleventy templates/configs under site/src/ and site/eleventy.config.js, never site/_site/.
• Honor the CSS budget — ZERO duplicate CSS, stay under the 1.5k LOC cap set in AGENTS.md.