Skip to content

Syntax-highlight lesson code blocks by language #128

Description

@ebouchut

Symptom

Fenced code blocks in lessons render monochrome: a ```java
fence shows the language-tagged markup the renderer already emits
(<code class="language-java">, kept through sanitization since
ADR-0013 exactly for this), but no highlighter exists to color it.

Design (summary; full decision in ADR-0017)

Same shape as the Mermaid decision (ADR-0016): the server keeps
shipping sanitized, text-only code blocks; the browser upgrades them.

  • highlight.js 11.11.1, self-hosted via the
    org.webjars.npm:highlightjs__cdn-assets WebJar (the plain
    highlight.js webjar ships no browser bundle since v11), version
    pinned, no CDN.
  • Lazy: lesson-highlight.js loads the bundle only when the lesson
    contains a language-* block other than language-mermaid.
  • Explicit languages only: blocks with unknown hints or bare fences
    stay monochrome; no auto-detect guessing.
  • Theme-token colors: no vendor CSS; hljs token classes map to the
    existing surface-safe accent tokens, so both themes pass WCAG AA by
    the contrast-audit proof.
  • Sanitizer untouched: highlighting reads text content client-side;
    no new server-side markup surface.

Acceptance criteria

  • Known-language fences (java, python, sql, bash, ...) render with
    colored tokens on the lesson page, in both themes.
  • Unknown-language and bare fences stay monochrome; mermaid fences
    are untouched (the diagram feature owns them).
  • The highlight bundle loads only on lessons that need it.
  • The existing renderer contract test (language-java survives
    sanitization) stays green; no sanitizer change.
  • axe (WCAG 2.1 A/AA) reports no new violations; full test suite
    and Checkstyle stay green.

Metadata

Metadata

Assignees

Projects

Status
Done

Relationships

None yet

Development

No branches or pull requests

Issue actions