All rules

Sheath rule

best-practices-require-doctype

HTML documents should have a <!DOCTYPE html> declaration.
Package
Core
Category
Best Practices
Default severity
warning by default
Auto-fix
Auto-fix available

(dangerous)

#Why

Without a DOCTYPE, browsers fall back to quirks mode, where box sizing and several layout behaviors follow pre-standards rules and differ between engines. <!DOCTYPE html> is what puts them all in standards mode.

#Examples

#Bad

<!-- Missing DOCTYPE -->

<html lang="en">

<head>

    <title>My Page</title>

</head>

<body>

    Content

</body>

</html>



<!-- Old DOCTYPE -->

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">

<html>

...

</html>

#Good

<!DOCTYPE html>

<html lang="en">

<head>

    <title>My Page</title>

</head>

<body>

    Content

</body>

</html>

#Auto-fix

The fixer declares <!DOCTYPE html> immediately above the <html> element:

<!-- Before -->

<html lang="en">



<!-- After -->

<!DOCTYPE html>

<html lang="en">

It anchors to <html> rather than to the top of the file, so Blade that renders to nothing keeps its place:

{{-- Before --}}

@php

    $theme = $user->theme;

@endphp

<html lang="en">



{{-- After --}}

@php

    $theme = $user->theme;

@endphp

<!DOCTYPE html>

<html lang="en">

An outdated declaration is rewritten in place rather than added to, because a document with two doctypes is worse off than the one it started with:

<!-- Before -->

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">

<html lang="en">



<!-- After -->

<!DOCTYPE html>

<html lang="en">

The fix is dangerous and requires --dangerous, because adding or replacing the doctype can switch the browser's rendering mode and change the page layout.

#Notes

  • DOCTYPE is case-insensitive (<!DOCTYPE html> and <!doctype html> are both valid)
  • Only full HTML documents with an <html> element are checked
  • Blade partials without <html> are not flagged
  • A license comment, @php block, or @props may appear before the doctype
  • A <!DOCTYPE html> that appears after <html> does not count, because by then the browser has already chosen a rendering mode

#References

#Related Rules