HTML Guides for script documentation

A script element with a src attribute has content other than whitespace and JavaScript comments between its tags.

When a script element has a src attribute, the browser loads and runs the external file and ignores whatever is written between <script> and </script>. The HTML standard therefore limits that content to "script documentation": whitespace, /* ... */ comments and // ... comments. Anything else is an error, and the message names the first character the validator didn't expect, such as the < of an HTML tag or the first letter of a statement. HTML comments (<!-- ... -->) are not allowed there either.

Two mistakes usually cause it. One is fallback markup placed inside the element, often copied from a widget's embed code: a link or a <span> meant to show if the script doesn't load. Browsers never render the content of a script element, so nobody sees that markup. The other is inline code added to a script that loads a file, expecting both to run. Only the external file runs, and the inline code is skipped without any warning.

Leave the element empty and move its content out. Put fallback markup in a <noscript> element, which is shown when JavaScript is disabled, or as regular content next to the script. Put inline code in its own <script> element without a src attribute. A /* ... */ comment inside the element is fine if you want to keep a note there; a // comment must be followed by a line break before </script>.

Invalid example

<script src="https://example.com/widget.js">

<a href="https://example.com/reviews">Read our reviews</a>

</script>

<script src="/js/analytics.js">

initAnalytics("site-123");

</script>

Valid example

<script src="https://example.com/widget.js"></script>

<noscript>

<a href="https://example.com/reviews">Read our reviews</a>

</noscript>

<script src="/js/analytics.js"></script>

<script>

initAnalytics("site-123");

</script>