What's the difference between quirks mode and standards mode?

Standards mode renders pages following modern web standards. Quirks mode emulates browser bugs from 1999-era browsers for legacy compatibility. In quirks mode: box-sizing differs, CSS layout calculates wrong, JavaScript APIs may differ, modern CSS features may not work. Browsers enter quirks mode when DOCTYPE is missing, malformed, or preceded by content. Result: subtle layout breakage and CSS that works in dev breaks in production.

Are old DOCTYPEs like XHTML still valid?

They still parse, but you should not use them on new builds. The HTML5 DOCTYPE works for all modern HTML, is the shortest, and is what browsers optimise for. XHTML 1.0/1.1 DOCTYPEs trigger 'almost standards mode' in some browsers, which has subtle differences from full standards mode. Just use HTML5 form.

Why does my WordPress site have whitespace before DOCTYPE?

Most common cause: a plugin or theme file has PHP closing tag ?> followed by a blank line or trailing whitespace. When that file is included before header.php fires, the trailing whitespace prints to the response before DOCTYPE. Fix: remove ?> from the end of PHP-only files entirely. PHP doesn't require the closing tag and removing it prevents accidental whitespace leakage.

Does DOCTYPE affect SEO directly?

Not directly — Google doesn't penalise missing DOCTYPE. Indirectly yes: quirks mode often breaks responsive layouts, which hurts mobile usability scores and Core Web Vitals (CLS especially). Layout shifts from quirks-mode rendering are a documented contributor to poor CLS scores.

How to Fix DOCTYPE Errors

The DOCTYPE declaration is the first line of every HTML document. It tells the browser which rendering mode to use. A missing or malformed DOCTYPE throws the browser into "quirks mode" — a backwards-compatibility mode that emulates 1999-era browser bugs. Quirks-mode pages render unpredictably, break responsive layout, and harm Core Web Vitals. The fix is one line, but the trap is whitespace before the DOCTYPE. This guide covers the fix and the platform-specific gotchas.

1. Verify your current DOCTYPE

Step 1

View page source

Right-click → View Page Source (or Ctrl+U). The very first line should be:

<!DOCTYPE html>

If the first line is blank, contains a BOM character, contains an XHTML DOCTYPE, or contains anything else — you have a problem.

Step 2

Check the rendering mode

Open browser DevTools → Console. Type:

document.compatMode

Expected: "CSS1Compat" (standards mode). If you get "BackCompat", the page is rendering in quirks mode and your DOCTYPE is wrong or missing.

2. Fix the DOCTYPE in your template

WordPress

Step 1

Edit header.php

In WP Admin → Appearance → Theme File Editor → header.php. The file should start with:

<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>

No blank lines, no whitespace, no PHP echo before the DOCTYPE line. If you're using a child theme, edit the child theme's header.php, not the parent.

Shopify

Step 1

Edit theme.liquid

Online Store → Themes → Actions → Edit code → layout/theme.liquid. First line should be:

<!DOCTYPE html>
<html lang="{{ request.locale.iso_code }}">

Shopify rarely has DOCTYPE issues since theme.liquid is tightly controlled, but custom themes sometimes inject Liquid output before the DOCTYPE.

Next.js (App Router)

Step 1

Next handles DOCTYPE automatically

Next.js emits the correct HTML5 DOCTYPE in its server output. You don't need to add it in your app/layout.tsx. If you see a DOCTYPE issue on a Next site, the cause is usually middleware or a custom server response that prepends content before Next renders. Audit middleware.ts and any custom response handlers.

3. The whitespace trap

⚠️ The most common DOCTYPE failure isn't a missing DOCTYPE — it's whitespace BEFORE the DOCTYPE. Even a single blank line or invisible BOM character pushes the browser into quirks mode.

Common causes of leading whitespace

Cause 1

PHP closing tags with trailing whitespace

A plugin file ends with:

function my_function() {
  // ...
}
?>
[BLANK LINE]

That blank line after ?> echoes to the response before the DOCTYPE. Fix: remove the closing ?> entirely. PHP doesn't require it and modern coding standards recommend omitting it in PHP-only files.

Cause 2

UTF-8 BOM in template files

Some editors save files with a UTF-8 Byte Order Mark (BOM) — three invisible bytes at the start of the file. The BOM echoes to the response before DOCTYPE. Re-save the template file as "UTF-8 without BOM" in your editor.

Cause 3

Plugin output buffering before theme

A plugin echoes diagnostic output (debug logs, admin notices to non-admins) before WordPress reaches header.php. Disable plugins one by one to identify the offender, then file a bug or replace the plugin.

4. Verify the fix

Step 1

Test via curl

curl -s https://yourdomain.com/ | head -c 100

Expected: response starts with <!DOCTYPE html> immediately. Any preceding character is a bug.

Step 2

Re-check in browser

In DevTools console: document.compatMode should return "CSS1Compat".

Step 3

Re-run the HTML Checker

Run the HTML Checker again. DOCTYPE finding should be cleared. While you're at it, fix any other validation warnings the checker reports.

💡 If you maintain multiple sites, add a CI lint step that checks every template file for: (a) no BOM, (b) no closing ?> in PHP-only files, (c) DOCTYPE as first non-whitespace content. Catches issues before deploy.

📐 Re-run the HTML Checker

Verify the DOCTYPE error is cleared and standards mode is active.

Run HTML Checker →