Use the HTML5 doctype
The HTML5 doctype declaration must appear as the first line of every HTML document to trigger standards mode rendering in all browsers.
- Every HTML document must begin with `<!DOCTYPE html>` as its very first line
- Without a doctype, browsers enter Quirks Mode — a legacy compatibility mode with inconsistent CSS and JavaScript behavior
- The HTML5 doctype is case-insensitive but `<!DOCTYPE html>` (uppercase DOCTYPE) is the conventional form
- No other content, not even whitespace or BOM characters, should appear before the doctype
- Frameworks like Next.js, Nuxt, and Remix automatically include the doctype — verify in rendered HTML, not source templates
Rule Details
The HTML5 doctype declaration must be the very first line of every HTML document. It switches browsers into standards-compliant rendering mode.
Code Examples
<!-- ✅ Correct: HTML5 doctype as the first line -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Page Title</title>
</head>
<body>
<!-- content -->
</body>
</html><!-- ❌ Incorrect: missing doctype -->
<html lang="en">
<head>
<title>Page Title</title>
</head>
<!-- ❌ Incorrect: old XHTML 1.0 doctype -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- ❌ Incorrect: HTML 4.01 Strict doctype -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">Why It Matters
- Box Model: In Quirks Mode,
widthandheightinclude padding and border (like the old IE box model), breaking CSS layouts. - CSS Features: Many modern CSS properties behave differently or are ignored in Quirks Mode.
- JavaScript APIs: Some DOM APIs behave differently in Quirks Mode.
- Validation: HTML5 documents without the doctype fail W3C validation.
Rendering Modes
| Mode | Triggered by | Behavior |
|---|---|---|
| Standards Mode | <!DOCTYPE html> present | CSS/HTML behaves per W3C specifications |
| Almost Standards Mode | Some HTML4 doctypes | Minor table rendering quirks |
| Quirks Mode | Missing or unrecognized doctype | Emulates IE5/Netscape 4 behavior |
Framework Notes
Most modern frameworks handle the doctype automatically:
- Next.js: Included automatically in the rendered HTML output
- Vite / Vue CLI: Present in
index.htmltemplate - Create React App: Present in
public/index.html - Astro: Included automatically
- Ruby on Rails: Present in
application.html.erb
Always verify in the rendered HTML source (browser: View Source), not just the template file, as SSR configurations can sometimes omit or move elements.
Standards
- Use HTML Living Standard: The DOCTYPE as the standard for the final rendered HTML and browser-facing behavior.
- Use MDN: DOCTYPE as the standard for the final rendered HTML and browser-facing behavior.
- Use MDN: Quirks Mode and Standards Mode as the standard for the final rendered HTML and browser-facing behavior.
Verification
Automated Checks
- Inspect the final rendered HTML in the browser or page source to confirm the rule is satisfied.
- Validate the affected markup with browser tooling or an HTML validator where appropriate.
- Test one representative route or template that uses the pattern.
- Re-check shared components that emit the same markup so the fix is consistent.
Manual Checks
- Verify the rendered browser behavior manually on representative routes and supported browsers so the user-facing outcome matches the rule.
Use with AI
Copy these prompts to use with your AI assistant, or install the MCP server to use directly from Claude, Cursor, or Windsurf.
Check
Verify implementation
Check the very first line of the HTML document source (not the DOM — the raw HTTP response). The document must begin with `<!DOCTYPE html>` (case-insensitive). Flag if: (1) the doctype is missing entirely; (2) an old HTML4 or XHTML doctype is used (contains PUBLIC and a DTD URL); (3) the doctype is not the absolute first content (whitespace or BOM before it triggers some browsers to enter Quirks Mode); (4) the doctype has incorrect syntax.
Fix
Auto-fix issues
Add `<!DOCTYPE html>` as the absolute first line of the HTML document, before the `<html>` tag. Remove any old HTML4 or XHTML doctypes. Ensure no whitespace, comments, or BOM markers precede the doctype. For framework projects: verify in the root HTML template file, and confirm in the rendered HTML by viewing page source in the browser.
Explain
Learn more
The DOCTYPE declaration tells the browser which version of HTML the document uses. `<!DOCTYPE html>` activates Standards Mode (also called Full Standards Mode) in all modern browsers, ensuring consistent rendering behavior. Without it, browsers enter Quirks Mode to emulate old IE behavior — a compatibility mode that changes the box model, float clearing, table rendering, and other CSS behaviors. The HTML5 doctype was intentionally made simple (just `<!DOCTYPE html>`) to replace the verbose HTML4/XHTML doctypes that required a full DTD URL.
Review
Code review
Review templates, server-rendered HTML, and shared components that output markup related to Use the HTML5 doctype. Flag exact elements, attributes, and routes where the rendered HTML violates the rule.