Doctype Errors: Fixing a Missing or Wrong Doctype

What the doctype actually does

In the early days of CSS, browsers disagreed about basic sums such as how wide a box is once padding and borders are added. When browsers were later corrected to follow the standards, millions of existing pages relied on the old, wrong behaviour. The compromise was doctype sniffing: pages that declared a modern doctype got the standards behaviour, and pages without one kept the old behaviour so they would not suddenly break.

That compromise survives in every current browser. The HTML specification defines three modes:

Only the first is what you want. The doctype does not tell the browser which version of HTML you wrote, and it does not switch features on or off. It is purely a switch between rendering modes, which is why the modern version is so short.

The messages you will see and what they mean

The HTML Checker follows the same wording as the W3C Nu validator, so the messages below are the ones to search your report for.

Start tag seen without seeing a doctype first

The parser reached an element, usually <html> or <head>, before any doctype. Either the doctype is missing from the template altogether, or the page is assembled from pieces and the piece that holds the doctype is not being included. The page is in quirks mode.

Non-space characters found without seeing a doctype first

Some visible text arrived before the doctype. This is the classic sign of a server-side script printing something too early: a PHP notice, a debugging echo, a stray character left in an include file, or a plugin writing output when it loads. The page is in quirks mode, and the stray text often appears as a line at the top of the screen.

Obsolete doctype. Expected <!DOCTYPE html>

The page uses an older declaration such as HTML 4.01 Strict or XHTML 1.0 Strict. These still give standards mode, so the layout is probably fine, but the validator flags them because they are no longer conforming. Replacing them is a one-line change.

Almost standards mode doctype. Expected <!DOCTYPE html>

A transitional or frameset doctype is putting the page into limited-quirks mode. The visible symptom is usually a few pixels of space under images in tables or in elements styled as table cells.

Quirky doctype. Expected <!DOCTYPE html>

The doctype exists but is one of the forms that browsers deliberately treat as quirks mode, for example HTML 4.01 Transitional written without its URL. Some very old site builders and email tools output these.

Stray doctype

A doctype appeared after the document had already started. This almost always means a complete HTML document has been pasted or included inside another one. The second doctype is ignored by the browser, but the <html>, <head> and <body> tags that come with it produce a cascade of further errors.

What is allowed before the doctype

There is a lot of folklore about the first line of an HTML file. The actual rules are narrower than many tutorials suggest. According to the HTML specification, a document may begin with the following before the doctype without any effect on the rendering mode:

• A byte order mark. The invisible BOM that some editors add to UTF-8 files is permitted at the very start of the document and is used by browsers to detect the encoding. It is not an error, although it can cause other trouble in PHP includes, which the character encoding guide covers.
• Whitespace. Blank lines and spaces before the doctype are allowed and do not trigger quirks mode in current browsers.
• Comments. An HTML comment such as a build stamp can sit above the doctype. Some very old versions of Internet Explorer mishandled this, which is where the advice to avoid it comes from, but it is conforming HTML.

What is not allowed is any other character: text, a tag, a PHP warning, an XML declaration in a page served as text/html that is then followed by other stray output, or a second copy of the page. So when you hunt for the cause, you are looking for visible characters, not whitespace.

Proving what the browser received

The fastest check is the browser console. Open the page, open developer tools and run this in the console:

document.compatMode
// "CSS1Compat"  means standards or limited-quirks mode
// "BackCompat"  means quirks mode

document.doctype
// shows the doctype node the parser found, or null if there was none

document.compatMode cannot tell standards mode from limited-quirks mode, so if it says CSS1Compat but you suspect a transitional doctype, read document.doctype.publicId and document.doctype.systemId. Firefox also prints a console message when a page loads in quirks mode.

Next, look at what the server actually sends rather than what your template file contains. View Source is good, but it can hide invisible characters. From a terminal:

curl -s https://www.example.co.uk/ | head -c 200 | od -c | head -8

This prints the first 200 bytes one character at a time. You should see the doctype immediately, optionally preceded by the three BOM bytes (shown as 357 273 277) or whitespace. Anything else in front of it is the cause of your problem.

Test more than the home page

Doctype problems are often confined to one template. A shop may have a correct home page while product pages load a different header file, or an error page, search results page or print view may be built by separate code. Run the HTML Checker on one page of each type, and include pages behind query strings, such as filtered listings, which sometimes go through a different code path.

Where the doctype lives on common platforms

The line should read exactly this, with the html element and the character encoding following immediately:

<!DOCTYPE html>
<html lang="en-GB">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Garden rooms and summerhouses | Larchfield Timber</title>

The fix, step by step

Layout changes to expect after the switch

Fixing a doctype on a page that has been in quirks mode for years sometimes looks like it broke the page. It did not; it exposed CSS that only worked because of legacy behaviour. These are the differences you are most likely to notice:

• Box sizes. Under standards rules, width means the content width and padding and borders are added on top. Many designs now set box-sizing: border-box on all elements to get the intuitive behaviour without relying on quirks mode.
• Percentage heights. In quirks mode, height: 100% on the body often fills the window. In standards mode it needs the html element to have a height too, or you can use viewport units such as min-height: 100vh instead.
• Gaps under images. Images are inline by default and sit on the text baseline, leaving a small gap below them. Setting display: block or vertical-align: middle on the images removes it.
• Table text size. In quirks mode, tables do not inherit the font size from the page. After the switch, text in tables may suddenly match the rest of the page and appear larger or smaller than before.
• Unitless lengths. Quirks mode accepts values such as width: 300 without a unit in some cases. Standards mode ignores them, so add px where it is missing.

Edge cases

• Pages served as XHTML. A document sent with the application/xhtml+xml content type is parsed as XML and never enters quirks mode, whatever its doctype. This is rare on public websites; most XHTML-looking pages are actually served as text/html and follow the normal rules.
• The legacy-compat doctype. <!DOCTYPE html SYSTEM "about:legacy-compat"> is a permitted alternative for tools that cannot output the short form. It is valid, gives standards mode, and does not need changing.
• Iframes. Each iframe has its own document and its own mode. A widget in an iframe can be in quirks mode while your page is not; fixing it is the widget provider's job.
• HTML emails. Email templates often keep an XHTML Transitional doctype on purpose because of how some email clients behave. Emails are outside the scope of the website checker.
• Fragments loaded by JavaScript. HTML snippets fetched and inserted into a page should not have a doctype at all. If you validate such a snippet on its own, ignore the missing doctype message.
• Error pages from the server or CDN. Default 404 and 500 pages generated by the web server, a load balancer or a CDN may have no doctype. Replace them with custom error pages built from your normal template.

Keeping it fixed

• One base layout. Make every page type extend a single base layout that owns the doctype, the html element and the charset. Pages built outside it are where the problem returns.
• Errors to logs, not screens. Production servers should log PHP and application errors rather than print them. That removes the most common source of text before the doctype.
• An automated check. A simple test that fetches key URLs and fails if the response body does not start with the doctype, after an optional BOM and whitespace, catches regressions in a deployment pipeline.
• Regular validation. Rerun the HTML Checker after theme updates, plugin installs and migrations, which are the moments doctypes most often change.