Site Auditing & Quality Assurance

StaticForge isn't just about building sites; it's about building correct sites. The system includes a comprehensive suite of audit tools designed to catch issues—from broken links to missing SEO tags—before your visitors do.

Why Audit?

In the dynamic world of CMSs (like WordPress), errors often happen at runtime. In the static world, we have the luxury of checking everything before deployment.

StaticForge divides auditing into four distinct phases:

Configuration: Is the environment set up correctly?
Content: Is the source content valid?
Build: Does the generated HTML work (links, images)?
Live: Is the production server secure and performant?

Phase 1: Configuration Audit

The audit:config command validates your project structure, environment variables (.env), and feature settings. It ensures you haven't missed critical settings like SITE_BASE_URL. If your project has a content/404.md (or 404.html), it also warns when SITE_BASE_URL is not a full URL, because 404 pages are served from any path and need absolute links. It also validates the feed key in siteconfig.yaml: enabled must be true or false, limit a positive integer, formats and category_formats lists of rss, atom, or json, and exclude_categories a list of category names. The upload key is checked too, with the same rules site:upload applies: max_delete must be unset or an integer of 0 or more, and strategy must be in_place.

When to run: When setting up a new machine, deploying for the first time, or troubleshooting weird behavior.

php bin/staticforge.php audit:config

Phase 2: Content Audit

The audit:content command scans your source markdown files (content/). It validates Frontmatter syntax and ensures required fields (like title and layout) are present.

When to run: While writing or integrating content from other people.

php bin/staticforge.php audit:content

Phase 3: Link & SEO Audit

These checks happen after you run site:render. They check the final HTML output.

Link Validation (`audit:links`)

This tool crawls your output/ directory and checks every <a> tag.

Internal Links: Verifies that links to other pages on your site actually exist.
External Links: (Optional) Pings external websites to ensure they are still up.

TLS Note: External checks validate HTTPS certificates by default. If you are testing a local or self-signed site, use --insecure.

Best Practice: Run internal checks on every build. Run external checks weekly to prevent "link rot."

# Fast: Check internal links only
php bin/staticforge.php audit:links --internal

# Thorough: Check everything (may be slow)
php bin/staticforge.php audit:links

# Allow self-signed or local certs (not recommended for production checks)
php bin/staticforge.php audit:links --insecure

SEO Validation (`audit:seo`)

Ensures your pages are search-engine friendly. It checks for:

Unique Page Titles
Meta Descriptions (presence and length)
Canonical URLs

php bin/staticforge.php audit:seo

Phase 4: Live Site Audit

The audit:live command is unique because it checks your hosted website, not your local files. It verifies that your web server is sending the correct security headers.

Checks performed:

SSL certificate: Verifies the certificate is trusted and issued for your hostname, and warns when it expires within 14 days. With --insecure, only the expiry date is reported.
HSTS: Ensures SSL is enforced.
X-Content-Type-Options: Prevents MIME-sniffing attacks.
X-Frame-Options: Prevents clickjacking.
Soft 404: Requests two random addresses that do not exist (one plain, one ending in .html) and expects 404 for both. A redirect or a 200 is reported as an error. See 404 Pages.

When to run: Immediately after deploying to production.

php bin/staticforge.php audit:live

# Allow self-signed or local certs (not recommended for production checks)
php bin/staticforge.php audit:live --insecure

Site Auditing