Opens in a new tabSkip to content
Agent LighthouseAgent Lighthouse

    Searches the text of every published page. The evidence sources themselves are not in this index — search all of them on the trusted sources page.

    GitHub ↗
    Browse checks and page contents
    content-extraction/code-language

    Code blocks have language annotations

    What it checks

    AI agents use language annotations on code blocks to apply the correct syntax understanding and provide accurate code explanations. Without them, agents must guess the programming language, which can lead to incorrect interpretations in AI-generated code answers.

    Why it matters

    An HTML-to-Markdown converter of the kind that feeds page text to LLMs emits a fenced code block whose info string names the language only when the <code> element carries a language-* class. Without that class the fence is emitted unlabeled, and the language must be inferred from the code text itself.

    Evidence

    • WHATWG HTML Standard §4.5.15 (code element): “There is no formal way to indicate the language of computer code being marked up. Authors who wish to mark code elements with the language used, e.g. so that syntax highlighting scripts can use the right rules, can use the class attribute, e.g. by adding a class prefixed with “language-” to the element.” The spec’s own example is <pre><code class="language-pascal">…</code></pre> — the exact pre > code idiom the audit queries. Note the named consumer is “syntax highlighting scripts”, not AI agents — html.spec.whatwg.org/…/text-level-semantics.html (verified 2026-08-21)
    • Turndown, the widely used HTML→Markdown library, derives the fence language from precisely this class in its fencedCodeBlock rule: const className = node.firstChild.getAttribute('class') || '' then const language = (className.match(/language-(\S+)/) || [null, ''])[1] — raw.githubusercontent.com/…/commonmark-rules.js (verified 2026-08-21)
    • Jina Reader, an HTML-to-Markdown service built for LLM consumption, uses Turndown as its conversion engine; it exposes x-md-* headers to “fine-tune markdown output” via src/dto/turndown-tweakable-options.ts. It returns markdown, frontmatter and chunked output for language models. The language-* class is therefore a real, traceable input to at least one production agent-facing pipeline — github.com/…/reader (verified 2026-08-21)

    Limits

    No AI vendor documentation states that any agent reads code-block language classes, and no published study measures a change in AI answer quality attributable to them. The causal step from “fence is labeled” to “agent explains the code correctly” is untested. Modern LLMs also identify programming languages from source text without an annotation. The convention is also not the only one in use. The HTML Standard itself concedes “there is no formal way”. Shiki’s data-language on <pre>, GitHub-style lang-* and Prism’s class-on-<pre> are all in live use. Turndown’s language- regex on node.firstChild matches none of them. That weakens the practical reach of the one traceable consumer path as much as it weakens the audit’s detector.

    How it scores

    The convention is explicitly described in the HTML Standard, and mechanically consumed by the Markdown converter behind common LLM-facing readers. But no vendor documents an AI agent reading it, and no study measures an effect on answer quality. The mechanism is plausible and unproven.

    Sources