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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions