sitemd.cc

Site Diagnostics

Every activated build includes a diagnostic layer that detects broken feature states on deployed sites. Instead of a blank page or a cryptic error, you get a styled error page, a console log with fix instructions, and an in-page overlay for partial failures.

How does it work?

sitemd production builds generate three diagnostic mechanisms:

Mechanism When it fires What it covers
500.html error page Hosting platform returns HTTP 500 Server-level failures, broken deploys, missing files
Inline diagnostic script Page loads but auth/data features fail Script 404s, license check failures, provider misconfiguration
Build-time warnings During sitemd build Missing auth.js or data.js when a provider is configured

All three are automatic. No configuration needed.

The 500 error page

Every production build writes a 500.html file to the site root, alongside the existing 404.html. Major hosting platforms serve this page when a server error occurs:

The page uses your site's theme, brand name, and favicon. Visitors see a clean "This site is experiencing a temporary issue" message with a link back to the homepage.

Console diagnostics

Open your browser's developer console on the 500 page to see fix instructions:

[sitemd] Site Error Diagnostics
  Your site returned a 500 error.
  This typically means:
    1. Auth or data scripts were not properly included during the last build
    2. The build produced incomplete output
    3. The hosting platform encountered a configuration issue

  To fix:
    1. Rebuild:  sitemd build
    2. If build warns about modules:  sitemd auth login
    3. Redeploy: sitemd deploy

Build metadata

The 500 page includes an HTML comment with build metadata. View source to see:

<!-- sitemd-build: {"mode":"activated","built":"2026-03-27T...","pages":12} -->

This tells you the build mode and how many pages were generated — useful for diagnosing whether the build itself was the problem.

Inline diagnostic overlay

When a page loads successfully (HTTP 200) but auth or data features fail, an inline diagnostic script detects the failure and shows a small overlay in the top-right corner of the page.

This covers failures that happen after the page renders:

Failure Detection method Timing
auth.js or data.js returns 404 Script onerror event Immediate
License check fails sitemd:auth-failed / sitemd:data-failed events Within seconds
Script loads but never initializes Timeout (8 seconds) Delayed
Page content stuck hidden DOM state check At timeout
Gated sections permanently hidden DOM state check At timeout

What the overlay looks like

A small dark card appears in the top-right corner with the primary issue. Click the dismiss button to hide it for the current browser session.

The overlay also unhides page content if the auth flash-prevention script had hidden <main> — showing broken content is better than showing nothing.

Console messages

Each detected issue logs a specific fix to the browser console:

Issue Console message
Script 404 auth.js failed to load — Fix: sitemd auth login && sitemd build && sitemd deploy
License failure Auth module license check failed — Fix: sitemd deploy (re-verifies activation)
Init failure auth.js loaded but failed to initialize — Fix: check provider settings in settings/auth.md
Hidden content Page content is hidden (auth flow incomplete) — symptom of the above issues

Where it runs

The diagnostic script is injected into activated build pages that reference auth.js or data.js. It does not run:

Build-time warnings

When you run sitemd build with an auth or data provider configured but the corresponding runtime file is missing from the output, the build logs a warning:

  ⚠ Auth is configured but auth.js is missing from the build output.
    Fix: Run "sitemd build" while connected to the internet to refresh modules.

This catches the problem before you deploy. The most common cause is building without a valid activation. Authenticate and activate your site, then rebuild.

Common scenarios

Deployed site shows a 500 error

The hosting platform can't serve the site. Open the 500 page's console for diagnostics, then:

  1. Run sitemd build — check for warnings
  2. If modules are missing: sitemd auth login to refresh credentials
  3. Redeploy: sitemd deploy

Page loads but is blank

The auth flash-prevention script hid content and auth.js never initialized. The diagnostic overlay will appear and unhide the page. Check the console for the specific failure (usually a license or provider issue).

Gated content never appears

auth.js didn't complete initialization, so gated sections stay hidden. The overlay detects this after 8 seconds. Fix the underlying auth issue — usually redeploying via sitemd deploy.

Build warns about missing files

The site's authentication has expired. Run sitemd auth login to re-authenticate, then sitemd deploy to rebuild and deploy.