HTML Guides for comment

Nested comments are not allowed in HTML. When you place an opening comment tag <!-- within an existing comment, it causes a parsing error.

To fix this issue, you should avoid nesting comments. If you need to include multiple comments in your HTML code, you can separate them or consider alternative ways to convey the information without nested comments.

Here's an example of a nested comments, which is not allowed in HTML:

<!-- This is a valid comment -->

<!-- This <!-- is not allowed --> nested comment -->

To fix the nested comment issue, you can rewrite the comments like this:

<!-- This is a valid comment -->

<!-- Avoid nesting comments and provide comments separately -->

<!-- Another comment here -->

XML 1.0 doesn't allow a comment to end with a hyphen, and in HTML pages this usually comes from PHP code that never ran or from a comment typed with single hyphens, such as <!- note ->.

When the HTML parser meets <?, or <! without -- or DOCTYPE after it, or </ followed by something other than a letter, it reads everything up to the next > as a "bogus comment". If the character right before that > is a hyphen, the comment text ends with -. Browsers don't mind, but an XML 1.0 comment can't end that way, so the validator flags it. Look for an error at the same spot, such as Bogus comment. or one about XML processing instructions. Fixing that error clears this warning too.

PHP that reaches the browser without being run is a typical source, because its -> operator puts a - right before a >. If the server sends <?php echo $page->title; ?> as is, the bogus comment starts at <? and stops inside ->. The rest of the code, title; ?>, shows up on the page as plain text. Check that the server runs the file through PHP (usually it needs a .php extension) and that PHP is enabled for that directory. If the code is meant to be shown on the page, as in a tutorial, escape the < as <.

The other usual source is a comment typed as <!- note -> with single hyphens. HTML comments open with <!-- and close with -->.

Invalid example

<!- Main navigation ->

<nav>

<a href="/">Home</a>

</nav>

<h1><?php echo $page->title; ?></h1>

Valid example

<!-- Main navigation -->

<nav>

<a href="/">Home</a>

</nav>

<h1>About us</h1>

The HTML specification restricts what can appear inside a comment. Specifically, a comment must not contain the string -- (two consecutive hyphens) except as part of the opening and closing delimiters. This rule originates from SGML and XML 1.0, where -- is treated as a comment delimiter, and having extra occurrences inside the comment body creates ambiguity about where the comment starts and ends.

While most modern browsers are lenient and will handle comments with double hyphens without issues, the markup is technically invalid. This matters for several reasons:

• XML compatibility: If your HTML is served as XHTML or processed by XML parsers, double hyphens inside comments will cause parsing errors and potentially break the entire document.
• Standards compliance: The HTML living standard explicitly states that comments must not contain --, so validators flag this as an error.
• Predictable parsing: Different parsers may interpret malformed comments differently, leading to inconsistent behavior across tools, crawlers, and assistive technologies.

To fix the issue, look inside your comment text and replace any occurrence of -- with something else, such as a single hyphen, an equals sign, or a different separator.

Examples

Incorrect: double hyphens inside the comment body

<!-- This is a separator ---------- end of section -->

The string of hyphens inside the comment contains multiple consecutive -- pairs, making the comment invalid.

<!-- Do not use -- as a separator -->

Here, -- appears literally in the comment text, which violates the rule.

<!-- TODO -- fix this later -- maybe next sprint -->

Multiple -- sequences appear as casual text separators, each one triggering the validation error.

Correct: avoiding double hyphens

Replace double hyphens with a different character or pattern:

<!-- This is a separator ========== end of section -->

<!-- Do not use dashes as a separator -->

<!-- TODO: fix this later, maybe next sprint -->

Correct: standard comment syntax

Simple comments that don't contain -- in their body are perfectly valid:

<!-- This is a valid comment -->

<!--

Multi-line comments are fine too,

as long as they don't contain double hyphens.

-->

Common pitfall: decorative comment borders

Developers sometimes use hyphens to create visual separators in their source code:

<!-- -------------------------------- -->

<!-- Navigation Section -->

<!-- -------------------------------- -->

Replace these with a different character:

<!-- ================================ -->

<!-- Navigation Section -->

<!-- ================================ -->

Or simply remove the decorative lines:

<!-- Navigation Section -->