HTML Guides for code

The lang attribute on any HTML element must be a valid IANA language subtag (like en, fr, or ja), not a programming language name.

The lang attribute specifies the natural (human) language of the element’s content, used by browsers, screen readers, and search engines for accessibility and localization purposes. Values like csharp, javascript, or python are not valid because they are not human languages registered in the IANA Language Subtag Registry.

This issue commonly arises when using <code lang="csharp"> to indicate the programming language of a code snippet. While the intention makes sense, lang is not the right attribute for this purpose.

To indicate a programming language on a <code> element, the recommended convention from the HTML specification is to use the class attribute with a language- prefix (e.g., class="language-csharp"). This is also the pattern used by popular syntax highlighting libraries like Prism.js and highlight.js.

If the code content is written in a specific human language (like English), you can still use lang="en" alongside the class.

Bad Example

<pre>
  <code lang="csharp">
    Console.WriteLine("Hello, World!");
  </code>
</pre>

Good Example

<pre>
  <code class="language-csharp">
    Console.WriteLine("Hello, World!");
  </code>
</pre>

The language tag yaml is reserved by IANA and cannot be used as a value for the lang attribute, which expects a valid BCP 47 language tag (like en for English or fr for French).

The lang attribute specifies the natural language of an element’s content — human languages like English, Spanish, or Japanese. It is not meant to indicate a programming or markup language. When you write lang="yaml" on a <code> element, the validator rejects it because yaml is a reserved IANA subtag with no valid use in BCP 47.

If your goal is to identify the code language for syntax highlighting or styling purposes, use the class attribute instead. A common convention, recommended by the HTML specification itself, is to use a class prefixed with language-, such as class="language-yaml".

HTML Examples

❌ Invalid: using lang for code language

<pre>
  <code lang="yaml">
    name: my-project
    version: 1.0.0
  </code>
</pre>

✅ Valid: using class for code language

<pre>
  <code class="language-yaml">
    name: my-project
    version: 1.0.0
  </code>
</pre>

This class="language-*" convention is widely supported by syntax highlighting libraries like Prism.js and highlight.js.

The <code> element is an inline-level (phrasing content) element designed to represent a fragment of computer code. According to the HTML specification, it can only contain other phrasing content — elements like <span>, <em>, <strong>, <a>, and text nodes. It cannot contain block-level (flow content) elements such as <div>, <p>, <ul>, <h1>–<h6>, or <table>.

When the validator reports that an end tag </code> violates nesting rules, it means one of two things is happening:

1. Disallowed content inside <code>: A block-level element has been placed inside the <code> element. When the browser encounters a block-level element where only phrasing content is allowed, it may implicitly close the <code> element. The subsequent </code> end tag then has no matching open tag, causing the nesting violation.

2. Overlapping or misnested tags: Tags inside <code> are improperly overlapped, meaning an element opened inside <code> is closed outside it, or vice versa.

This matters for several reasons. Browsers will attempt to “fix” the broken nesting by rearranging the DOM in ways you may not expect, leading to inconsistent rendering and styling. Screen readers and other assistive technologies rely on a well-formed DOM tree, so broken nesting can harm accessibility. Additionally, other validator errors in your document may cascade from this single nesting issue, so fixing it can resolve multiple warnings at once.

When debugging this error, look at other validation errors reported near the same line. Often, a prior error — such as an unclosed tag or an unexpected block element — is the root cause, and the </code> nesting violation is a downstream consequence.

Examples

❌ Block-level element inside <code>

Placing a <div> inside <code> violates the content model. The browser implicitly closes <code> before the <div>, leaving the </code> end tag orphaned.

<p>Example: <code>some text <div>block content</div> more text</code></p>

✅ Use only phrasing content inside <code>

Replace the block-level element with an inline alternative like <span>:

<p>Example: <code>some text <span>inline content</span> more text</code></p>

❌ Overlapping tags with <code>

Here, <em> is opened inside <code> but closed after </code>, creating an overlap:

<p>See <code>myFunction(<em>arg</code>)</em> for details.</p>

✅ Properly nested tags

Ensure every element opened inside <code> is also closed inside it:

<p>See <code>myFunction(<em>arg</em>)</code> for details.</p>

❌ Paragraph inside <code>

A <p> element is not allowed inside <code>:

<code>
  <p>First line of code</p>
  <p>Second line of code</p>
</code>

✅ Use <pre><code> for multi-line code blocks

For multi-line code, wrap <code> inside a <pre> element and use line breaks instead of paragraphs:

<pre><code>First line of code
Second line of code</code></pre>

❌ List inside <code>

<code>
  <ul>
    <li>step one</li>
    <li>step two</li>
  </ul>
</code>

✅ Separate the list from the code markup

Use <code> individually around the inline code portions:

<ul>
  <li><code>step one</code></li>
  <li><code>step two</code></li>
</ul>

How to Fix

1. Find the line referenced by the validator error and look at what’s inside the <code> element.
2. Check for block-level elements like <div>, <p>, <ul>, <table>, or headings nested inside <code>. Replace them with phrasing content alternatives or restructure your markup.
3. Check for overlapping tags where an element started inside <code> is closed outside it (or the reverse). Make sure every tag opened inside <code> is closed inside it.
4. Review related errors in the validator output. Often, fixing an earlier nesting or unclosed-tag error will resolve the </code> violation automatically.