Fix Missing HTML Doctype for Better Best Practices Score
Without a proper doctype, browsers render your page in quirks mode—a legacy compatibility mode that breaks modern CSS and causes unpredictable layout behavior.
What's Happening
The doctype declaration tells browsers which version of HTML your document uses. When it's missing or incorrect, browsers fall back to quirks mode, which emulates old browser bugs from the early 2000s. This means your carefully crafted CSS won't behave as expected—box models calculate differently, table layouts break, and modern features may not work at all.
Lighthouse flags this under "Page lacks the HTML doctype, thus triggering quirks-mode" when your document either has no doctype, uses an outdated doctype format, or includes unnecessary public/system identifiers.
Diagnose
Check Document Source
View your page source (Ctrl+U / Cmd+U) and look at the very first line. It should be exactly:
<!DOCTYPE html>
If you see any of these, you have a problem:
<!-- Missing entirely - no doctype at the top -->
<!-- Old HTML 4.01 doctype (triggers limited-quirks) -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<!-- XHTML doctype -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
Check Compatibility Mode in DevTools
- Open DevTools (F12)
- Go to Console
- Run:
document.compatMode - If it returns
"BackCompat", you're in quirks mode "CSS1Compat"means standards mode (correct)
Fix
1. Add the HTML5 Doctype
Place this as the absolute first line of your HTML document—before any whitespace, comments, or other content:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!-- rest of head -->
</head>
The doctype must be:
- Exactly
<!DOCTYPE html>(case-insensitive, but lowercase is conventional) - No public ID
- No system ID
- Nothing before it in the document
2. Fix Server-Side Template Issues
If your doctype is correct in your source but missing in the rendered HTML, check your server-side templates.
PHP: Ensure no output before the doctype:
<?php
// Bad: whitespace before PHP tag can cause output
?>
<!DOCTYPE html>
<?php // Good: no whitespace before doctype ?>
<!DOCTYPE html>
Express/Node.js: Watch for BOM or whitespace in template files:
// If using template literals, watch for leading whitespace
const html = `<!DOCTYPE html>
<html>...</html>`
Static Site Generators: Check your base layout or template file. The doctype should be in your root layout, not repeated in partials.
3. Handle Dynamic Content
For single-page applications that manipulate the DOM, ensure the initial HTML shell includes the doctype:
<!-- public/index.html or equivalent -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>App</title>
</head>
<body>
<div id="app"></div>
<script src="/app.js"></script>
</body>
</html>
Verify the Fix
- View page source and confirm
<!DOCTYPE html>is on line 1 - Open DevTools Console and run
document.compatMode—should return"CSS1Compat" - Run Lighthouse and confirm the "Page has the HTML doctype" audit passes
- Check your layouts still render correctly (quirks mode may have been masking CSS issues)
Common Mistakes
- Whitespace before doctype — Even a single blank line or space before
<!DOCTYPE html>can trigger quirks mode in some browsers. Use your editor to verify there's no invisible BOM character. - Copying old doctypes from legacy code — HTML 4.01 and XHTML doctypes include public/system identifiers that trigger limited-quirks mode. Replace them with the simple HTML5 doctype.
- PHP/ASP output before doctype — Server-side scripts that output content (including whitespace or error messages) before the doctype will break standards mode.
- Incorrect case or typos — While browsers are forgiving about case, typos like
<!DOCTYP html>or<!DOCTYPE htm>will fail.
Test Your Entire Site
A missing doctype on one template can affect all pages using that layout. Scan your entire site to catch doctype issues across all routes.
Scan Your Site with Unlighthouse