From 5fdf359dc0f0ace799e0cd03eb510cc0f52c2033 Mon Sep 17 00:00:00 2001
From: Eric Bouchut <ebouchut@gmail.com>
Date: Mon, 27 Jul 2026 22:06:56 +0200
Subject: [PATCH 1/8] fix(frontend): Style the rendered lesson content

The lesson body looked unstyled next to the rest of the site: base.css
only covered h1 to h3, p, a, img, and bare code, so everything else the
Markdown produces (fenced code blocks, blockquotes, lists, tables,
deep headings, horizontal rules) fell back to raw browser defaults.
And since the sanitizer strips class attributes (ADR-0013), the
rendered HTML can never carry BEM classes, so nothing class-based
could ever reach it.

The lesson template now wraps the content in a lesson-content block,
and base.css styles it with element selectors scoped under that
wrapper (a deliberate, documented BEM exception, the only mechanism
the sanitized markup allows): code blocks become bordered cards that
scroll horizontally instead of stretching the page (RGAA 10.11),
inline code gets a chip, blockquotes an accent border, tables the
house table look, lists and deep headings the site rhythm, with h4 to
h6 joining the display typeface the global rule reserves for h1 to h3.
---
 src/main/resources/static/css/base.css        | 82 +++++++++++++++++++
 .../resources/templates/courses/lesson.html   |  2 +-
 2 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/src/main/resources/static/css/base.css b/src/main/resources/static/css/base.css
index 7f617e1..daa250e 100644
--- a/src/main/resources/static/css/base.css
+++ b/src/main/resources/static/css/base.css
@@ -590,3 +590,85 @@ textarea.form__input {
 .reveal--2 { animation-delay: 100ms; }
 .reveal--3 { animation-delay: 200ms; }
 .reveal--4 { animation-delay: 300ms; }
+
+/* ---------- Lesson content (rendered Markdown) ---------- */
+
+/* The lesson body is instructor Markdown rendered to sanitized HTML
+   (ADR-0013): the sanitizer strips class attributes, so BEM classes can
+   never reach this markup. Element selectors scoped under the wrapper
+   are the only way to style it (deliberate, documented BEM exception). */
+
+.lesson-content h2,
+.lesson-content h3,
+.lesson-content h4 {
+  margin-top: var(--space-5);
+}
+
+/* The global heading rule stops at h3; demoted headings go down to h6. */
+.lesson-content h4,
+.lesson-content h5,
+.lesson-content h6 {
+  font-family: var(--font-display);
+  line-height: 1.2;
+  margin: var(--space-4) 0 var(--space-3);
+  letter-spacing: -0.015em;
+}
+
+.lesson-content ul,
+.lesson-content ol {
+  margin: 0 0 var(--space-3);
+  padding-left: var(--space-5);
+}
+
+.lesson-content li {
+  margin-bottom: var(--space-1);
+}
+
+.lesson-content pre {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  padding: var(--space-3);
+  margin: 0 0 var(--space-3);
+  overflow-x: auto; /* long lines scroll inside the block, no page scroll (RGAA 10.11) */
+}
+
+/* Inline code gets a chip; code inside pre relies on the block styling. */
+.lesson-content :not(pre) > code {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-sm);
+  padding: 0.1em 0.35em;
+}
+
+.lesson-content blockquote {
+  margin: 0 0 var(--space-3);
+  padding: var(--space-1) var(--space-4);
+  border-left: 4px solid var(--color-primary);
+  color: var(--color-text-muted);
+}
+
+.lesson-content table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 0 0 var(--space-3);
+}
+
+.lesson-content th,
+.lesson-content td {
+  text-align: left;
+  padding: var(--space-2) var(--space-3);
+  border: 1px solid var(--color-border);
+}
+
+.lesson-content th {
+  font-family: var(--font-display);
+  font-size: var(--font-size-sm);
+  background: var(--color-surface);
+}
+
+.lesson-content hr {
+  border: 0;
+  border-top: 1px solid var(--color-border);
+  margin: var(--space-5) 0;
+}
diff --git a/src/main/resources/templates/courses/lesson.html b/src/main/resources/templates/courses/lesson.html
index 1e1a220..6ed6ee9 100644
--- a/src/main/resources/templates/courses/lesson.html
+++ b/src/main/resources/templates/courses/lesson.html
@@ -13,7 +13,7 @@
     <article>
       <h1 class="page-title" th:text="${lesson.title}">Lesson title</h1>
       <!-- contentHtml is rendered and sanitized by MarkdownRenderer (ADR-0013). -->
-      <div th:utext="${contentHtml}">Lesson content</div>
+      <div class="lesson-content" th:utext="${contentHtml}">Lesson content</div>
     </article>
 
     <nav aria-label="Lesson">

From 9b2babefb0ffec2ae7f671df8ebca765525b1f83 Mon Sep 17 00:00:00 2001
From: Eric Bouchut <ebouchut@gmail.com>
Date: Mon, 27 Jul 2026 22:07:16 +0200
Subject: [PATCH 2/8] feat(markdown): Render GFM pipe tables in lessons

Pipe tables are a GFM extension, not core CommonMark, so a table typed
in a lesson rendered as literal pipe-separated text; the fresh
lesson-content table styles had nothing to apply to. ADR-0013 planned
for exactly this: extensions join on demand, and a lesson demanded one.

commonmark-ext-gfm-tables now plugs into the parser and the renderer;
the sanitizer allowlist already lets table markup through, proven by
the new renderer test asserting a pipe table survives rendering and
sanitization as a real HTML table.
---
 pom.xml                                            |  7 +++++++
 .../learndev/course/MarkdownRenderer.java          | 12 +++++++++++-
 .../learndev/course/MarkdownRendererTest.java      | 14 ++++++++++++++
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/pom.xml b/pom.xml
index 25b6013..9974bb5 100644
--- a/pom.xml
+++ b/pom.xml
@@ -135,6 +135,13 @@
             <artifactId>commonmark</artifactId>
             <version>${commonmark.version}</version>
         </dependency>
+        <!-- GFM pipe tables in lesson Markdown (extension added on demand,
+             as ADR-0013 planned) -->
+        <dependency>
+            <groupId>org.commonmark</groupId>
+            <artifactId>commonmark-ext-gfm-tables</artifactId>
+            <version>${commonmark.version}</version>
+        </dependency>
         <dependency>
             <groupId>org.jsoup</groupId>
             <artifactId>jsoup</artifactId>
diff --git a/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java b/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java
index 47e38c4..5a92cdf 100644
--- a/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java
+++ b/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java
@@ -1,6 +1,8 @@
 package com.ericbouchut.learndev.course;
 
 import com.ericbouchut.learndev.common.config.CacheConfig;
+import org.commonmark.Extension;
+import org.commonmark.ext.gfm.tables.TablesExtension;
 import org.commonmark.node.Heading;
 import org.commonmark.node.Node;
 import org.commonmark.parser.Parser;
@@ -17,6 +19,7 @@
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 import java.util.HexFormat;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
@@ -40,8 +43,15 @@ public class MarkdownRenderer {
     private static final Safelist SAFELIST = Safelist.relaxed()
             .addAttributes("code", "class");
 
-    private final Parser parser = Parser.builder().build();
+    // GFM pipe tables, added on demand as ADR-0013 planned; the sanitizer
+    // allowlist already lets table markup through (Safelist.relaxed).
+    private static final List<Extension> EXTENSIONS = List.of(TablesExtension.create());
+
+    private final Parser parser = Parser.builder()
+            .extensions(EXTENSIONS)
+            .build();
     private final HtmlRenderer renderer = HtmlRenderer.builder()
+            .extensions(EXTENSIONS)
             .nodeRendererFactory(DemotedHeadingRenderer::new)
             .build();
 
diff --git a/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java b/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java
index a9fddf9..75c4165 100644
--- a/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java
+++ b/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java
@@ -96,6 +96,20 @@ void same_content_is_rendered_once_and_served_from_the_cache() {
         assertThat(markdownRenderer.render("Different content.")).isNotSameAs(first);
     }
 
+    @Test
+    void renders_gfm_pipe_tables_as_html_tables() {
+        // Arrange (Given): a GFM pipe table (extension, not core CommonMark)
+        String markdown = "| Concept | Example |\n|---------|---------|\n| Array | int[] |";
+
+        // Act (When)
+        String html = markdownRenderer.render(markdown);
+
+        // Assert (Then): a real table survives rendering and sanitization
+        assertThat(html).contains("<table>");
+        assertThat(html).contains("<th>Concept</th>");
+        assertThat(html).contains("<td>Array</td>");
+    }
+
     @Test
     void blank_content_renders_to_an_empty_string() {
         assertThat(markdownRenderer.render("")).isEmpty();

From 2056161870c440d94a228d72d0f4257ffcb2c645 Mon Sep 17 00:00:00 2001
From: Eric Bouchut <ebouchut@gmail.com>
Date: Tue, 28 Jul 2026 10:01:32 +0200
Subject: [PATCH 3/8] docs(plan): Add the lesson alerts and title dedup plan

Two lesson-rendering improvements land on this branch: alert/callout
blocks in the GitHub/Obsidian syntax (issue #116) and skipping a leading
heading that duplicates the lesson title (issue #117). The plan records
the commit map, the decisions involved, and the verification steps.
---
 ...026-07-28-lesson-alerts-and-title-dedup.md | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 docs/plans/2026-07-28-lesson-alerts-and-title-dedup.md

diff --git a/docs/plans/2026-07-28-lesson-alerts-and-title-dedup.md b/docs/plans/2026-07-28-lesson-alerts-and-title-dedup.md
new file mode 100644
index 0000000..e3a8f85
--- /dev/null
+++ b/docs/plans/2026-07-28-lesson-alerts-and-title-dedup.md
@@ -0,0 +1,32 @@
+# Lesson Alerts and Title Dedup Implementation Plan
+
+**Goal:** Two improvements to lesson Markdown rendering, on the `fix/lesson-content-styles` branch: (1) alert/callout blocks (`> [!note]`) in the syntax GitHub and Obsidian share, styled with octicons and theme accents (issue #116); (2) stop showing a duplicated heading when a lesson's Markdown starts with a level-1 heading equal to the lesson title (issue #117).
+
+**Architecture:** Both changes stay inside the rendering pipeline of [ADR-0013](../adr/0013-render-lesson-markdown-with-commonmark-java.md) and [ADR-0014](../adr/0014-demote-markdown-headings-in-lesson-rendering.md). Alerts are parsed by the official `commonmark-ext-gfm-alerts` extension (decision recorded in [ADR-0015](../adr/0015-render-lesson-alerts-with-commonmark-alerts.md)), which forces a commonmark 0.24.0 => 0.29.0 upgrade; sanitization stays allowlist-based with a second pass that rejects any class value the alert renderer does not emit. The title dedup is a pure static helper in `MarkdownRenderer`, applied by the lesson route before `render()` so the render cache stays content-addressed.
+
+**Out of scope:** alert support outside lessons, a Markdown preview in the lesson form, and any change to stored lesson content.
+
+---
+
+## Version Control (GitButler)
+
+- Commit with `but commit fix/lesson-content-styles -m "<msg>"` from the main repository; never `git add`/`git commit`.
+- **NEVER push.** The user reviews in GitButler and pushes manually.
+- One atomic commit per task below; tests land with the code they prove.
+
+---
+
+## Tasks
+
+- [ ] `docs(plan): Add the lesson alerts and title dedup plan` (this document)
+- [ ] `docs(adr): Record the lesson alert rendering decision` ([ADR-0015](../adr/0015-render-lesson-alerts-with-commonmark-alerts.md) plus the ADR index row)
+- [ ] `build(deps): Upgrade commonmark to 0.29.0` (version property only; required by the alerts extension, which is version-locked to its core; changelog reviewed, no API removals; full suite green proves tables, heading demotion, and caching survive)
+- [ ] `feat(markdown): Render GFM and Obsidian-style alerts in lessons` (alerts dependency; `MarkdownRenderer` wiring: 27 registered types where the five GFM types keep their GitHub identity and the Obsidian set joins them with aliases, custom titles, nesting; sanitizer allowlist for `div[class, data-alert-type]` and `p[class]` plus the `stripUnknownAlertClasses` second pass; renderer tests incl. a class-spoofing case)
+- [ ] `feat(frontend): Style lesson alerts with octicon icons` (alert styles in the `.lesson-content` section of `base.css`: accent border and title color per type family via theme tokens, octicons as `mask` data URIs colored by `currentColor`, nested alerts inset; closes #116)
+- [ ] `fix(markdown): Skip a leading heading duplicating the lesson title` (static `stripLeadingTitleHeading`; lesson route applies it before `render()`; tests for ATX/setext, case and whitespace tolerance, non-matching heading kept; lesson form hint; consequence note in [ADR-0014](../adr/0014-demote-markdown-headings-in-lesson-rendering.md); closes #117)
+
+## Verification
+
+- `make test` and `./mvnw checkstyle:check` green after the upgrade commit and again at the end.
+- Browser pass on a lesson exercising several alert types, nesting, and a custom title: correct icon, accent, and title in both themes; axe reports zero violations; no horizontal page scroll (RGAA 10.11).
+- A lesson whose Markdown starts with `# <lesson title>` renders exactly one heading with that text.

From b1120106eb596505712c31aa901aeb1c43d08922 Mon Sep 17 00:00:00 2001
From: Eric Bouchut <ebouchut@gmail.com>
Date: Tue, 28 Jul 2026 10:01:44 +0200
Subject: [PATCH 4/8] docs(adr): Record the lesson alert rendering decision

Lessons should render the alert/callout syntax GitHub and Obsidian
share. ADR-0015 chooses the official commonmark-ext-gfm-alerts
extension over a custom parser or a post-processing pass, accepts the
commonmark 0.24.0 => 0.29.0 upgrade it forces, keeps the five GFM types
on their GitHub identity while the Obsidian set joins with all aliases,
ships octicons as CSS masks so no SVG crosses the sanitizer, and
narrows the widened class allowlist with an exact-value second pass.

Refs #116
---
 ...er-lesson-alerts-with-commonmark-alerts.md | 107 ++++++++++++++++++
 docs/adr/README.md                            |   3 +-
 2 files changed, 109 insertions(+), 1 deletion(-)
 create mode 100644 docs/adr/0015-render-lesson-alerts-with-commonmark-alerts.md

diff --git a/docs/adr/0015-render-lesson-alerts-with-commonmark-alerts.md b/docs/adr/0015-render-lesson-alerts-with-commonmark-alerts.md
new file mode 100644
index 0000000..c22e673
--- /dev/null
+++ b/docs/adr/0015-render-lesson-alerts-with-commonmark-alerts.md
@@ -0,0 +1,107 @@
+# Render lesson alerts with the commonmark-java alerts extension
+
+- Status: accepted
+- Date: 2026-07-28
+- Deciders: Eric Bouchut
+
+## Context and Problem Statement
+
+Instructors write lesson content in Markdown (see
+[ADR-0013](0013-render-lesson-markdown-with-commonmark-java.md)) and expect
+the callout syntax they know from GitHub and Obsidian to work:
+`> [!note]`, `> [!tip] Custom title`, nested callouts. Plain CommonMark
+renders these as ordinary blockquotes with the marker as literal text. How
+should lessons render alert/callout blocks while keeping the sanitization
+pipeline allowlist-based and the rendered HTML free of author-controlled
+markup tricks?
+
+## Decision Drivers
+
+- Author familiarity: the GitHub/Obsidian syntax should just work, including
+  content pasted from either tool
+- ADR-0013's pipeline stays: parse, render, sanitize against an allowlist;
+  no raw SVG or style attributes may survive into the page
+- Maintenance cost: prefer an official, tested module over in-repo parser code
+- GitHub fidelity: content authored for GitHub must render with the same
+  type semantics as on GitHub
+
+## Considered Options
+
+- The official `commonmark-ext-gfm-alerts` extension (requires upgrading
+  commonmark 0.24.0 => 0.29.0)
+- A custom commonmark-java block parser and renderer kept in this repository
+- A jsoup post-processing pass that rewrites `[!note]` blockquotes after
+  rendering
+- Do nothing: callout markers render as literal blockquote text
+
+## Decision Outcome
+
+Chosen: "the official `commonmark-ext-gfm-alerts` extension", because it is
+maintained by the commonmark-java project itself, implements the exact GFM
+syntax plus the options needed to cover Obsidian (custom types, custom
+titles, nested alerts), and emits plain `div`/`p` markup with predictable
+class names that the sanitizer can allowlist precisely. The extension is
+version-locked to its same-version core and its configuration API only
+exists in 0.29.0, so the whole commonmark stack moves 0.24.0 => 0.29.0
+(changelog reviewed: no API removals; the notable parser change is that
+tables no longer require a preceding blank line).
+
+Configuration decisions that follow:
+
+- The five GFM types (`NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`) keep
+  their GitHub identity: `IMPORTANT` and `CAUTION` are registered as
+  standalone types, not as Obsidian aliases, so GitHub-authored content
+  renders with GitHub's semantics. The remaining Obsidian callout set joins
+  them with all aliases (27 registered types in total); markers are
+  case-insensitive; custom titles and nesting are enabled.
+- Icons are Octicons (the set GitHub uses for alerts), matched per type
+  against Obsidian's icon semantics, and shipped as CSS `mask-image` data
+  URIs colored by `currentColor`. The sanitizer therefore never has to let
+  SVG through.
+- The jsoup allowlist must now admit `class` on `div` and `p` plus
+  `data-alert-type`. To keep raw HTML in lessons from borrowing site classes
+  (`alert`, `site-header`, ...), a second sanitization pass strips every
+  class value the alert renderer does not emit: only
+  `markdown-alert markdown-alert-<type>` on `div` and `markdown-alert-title`
+  on `p` survive.
+
+### Consequences
+
+- Good: GitHub- and Obsidian-authored content renders as its authors expect,
+  with no house syntax to teach
+- Good: the sanitization posture of ADR-0013 is preserved; the allowlist
+  widens by two attributes and is immediately narrowed by an exact-value pass
+- Good: the commonmark stack is current again (0.24.0 dated from the initial
+  integration)
+- Trade-off: a major-feature upgrade of the Markdown stack rides along; the
+  full test suite is the regression net for tables, heading demotion, and
+  caching
+- Trade-off: 27 registered types means 27 CSS selectors and a set of icon
+  data URIs in `base.css`, a one-time styling cost paid in this change
+
+## Pros and Cons of the Options
+
+### Official commonmark-ext-gfm-alerts extension
+
+- 👍 Maintained upstream by the commonmark-java project, GFM-exact syntax
+- 👍 Options cover the full Obsidian feature set (types, titles, nesting)
+- 👍 Emits sanitizer-friendly `div`/`p` markup, no inline styles or SVG
+- 👎 Forces the 0.24.0 => 0.29.0 core upgrade in the same change
+
+### Custom block parser in this repository
+
+- 👍 No version constraint on the core
+- 👎 Reimplements and then maintains non-trivial parsing (nesting, titles,
+  lazy continuation) that upstream already tests
+
+### jsoup post-processing of rendered blockquotes
+
+- 👍 No parser changes at all
+- 👎 Fragile text matching inside rendered HTML; nesting and custom titles
+  get hard quickly; the marker has already been mangled by inline rendering
+
+### Do nothing
+
+- 👍 No code
+- 👎 Pasted GitHub/Obsidian content degrades into blockquotes with visible
+  `[!note]` markers, exactly what instructors would report as a bug
diff --git a/docs/adr/README.md b/docs/adr/README.md
index e479efb..30f53a1 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -44,4 +44,5 @@ NNNN-short-title-in-kebab-case.md
 | [0011](0011-start-ci-quality-checks-as-advisory-reports.md) | Start CI quality checks as advisory reports, gates come later | superseded by ADR-0012 |
 | [0012](0012-publish-test-coverage-to-codecov.md) | Publish test coverage to Codecov | accepted |
 | [0013](0013-render-lesson-markdown-with-commonmark-java.md) | Render lesson Markdown with commonmark-java, sanitized by jsoup | accepted |
-| [0014](0014-demote-markdown-headings-in-lesson-rendering.md) | Demote Markdown headings one level in lesson rendering | accepted |
\ No newline at end of file
+| [0014](0014-demote-markdown-headings-in-lesson-rendering.md) | Demote Markdown headings one level in lesson rendering | accepted |
+| [0015](0015-render-lesson-alerts-with-commonmark-alerts.md) | Render lesson alerts with the commonmark-java alerts extension | accepted |
\ No newline at end of file

From 93e0f7b4279c9d095afa8aecf625ff2f167b7e63 Mon Sep 17 00:00:00 2001
From: Eric Bouchut <ebouchut@gmail.com>
Date: Tue, 28 Jul 2026 10:04:37 +0200
Subject: [PATCH 5/8] build(deps): Upgrade commonmark to 0.29.0

The upcoming alerts extension (commonmark-ext-gfm-alerts) is version-
locked to its same-version core, and its configuration API (custom
types, custom titles, nested alerts) only exists in 0.29.0, so the
whole commonmark stack moves up from 0.24.0 in one step.

Changelog reviewed from 0.25.0 to 0.29.0: no API removals; the notable
parser change is that GFM tables no longer require a preceding blank
line. The full test suite (tables, heading demotion, render caching)
stays green on the new version.

Refs #116
---
 pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pom.xml b/pom.xml
index 9974bb5..c7814b5 100644
--- a/pom.xml
+++ b/pom.xml
@@ -58,7 +58,7 @@
         <maven-checkstyle-plugin.version>3.6.0</maven-checkstyle-plugin.version>
         <maven-javadoc-plugin.version>3.11.2</maven-javadoc-plugin.version>
         <jacoco-maven-plugin.version>0.8.15</jacoco-maven-plugin.version>
-        <commonmark.version>0.24.0</commonmark.version>
+        <commonmark.version>0.29.0</commonmark.version>
         <jsoup.version>1.21.1</jsoup.version>
     </properties>
 

From 4327f144806ce4dc87ffdffda226aa0a78533fdf Mon Sep 17 00:00:00 2001
From: Eric Bouchut <ebouchut@gmail.com>
Date: Tue, 28 Jul 2026 10:04:46 +0200
Subject: [PATCH 6/8] feat(markdown): Render GFM and Obsidian-style alerts in
 lessons

Alert markers in lesson Markdown ("> [!note]") used to degrade into
plain blockquotes with the marker as literal text. The official
commonmark-ext-gfm-alerts extension now plugs into the parser and
renderer with every option enabled, as decided in ADR-0015.

Registered types: the five GFM types keep their GitHub identity
(IMPORTANT and CAUTION stay standalone), and the full Obsidian callout
set joins them with all aliases, 27 types in total, matched case-
insensitively. Custom titles are inline-parsed and nested alerts
render as alerts instead of degrading to literal text.

The sanitizer allowlist widens to admit class on div/p and
data-alert-type so the alert markup stays styleable, and a second
sanitization pass immediately narrows it: any class value the alert
renderer does not emit is stripped, so raw HTML in a lesson cannot
borrow site classes. Renderer tests cover default and custom titles,
aliases, nesting, and the class-spoofing case.

Refs #116
---
 pom.xml                                       |  7 ++
 .../learndev/course/MarkdownRenderer.java     | 93 +++++++++++++++++--
 .../learndev/course/MarkdownRendererTest.java | 82 ++++++++++++++++
 3 files changed, 176 insertions(+), 6 deletions(-)

diff --git a/pom.xml b/pom.xml
index c7814b5..e28634d 100644
--- a/pom.xml
+++ b/pom.xml
@@ -142,6 +142,13 @@
             <artifactId>commonmark-ext-gfm-tables</artifactId>
             <version>${commonmark.version}</version>
         </dependency>
+        <!-- GFM/Obsidian-style alerts ("> [!NOTE]") in lesson Markdown;
+             needs commonmark >= 0.29.0 for custom types, titles, nesting -->
+        <dependency>
+            <groupId>org.commonmark</groupId>
+            <artifactId>commonmark-ext-gfm-alerts</artifactId>
+            <version>${commonmark.version}</version>
+        </dependency>
         <dependency>
             <groupId>org.jsoup</groupId>
             <artifactId>jsoup</artifactId>
diff --git a/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java b/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java
index 5a92cdf..45feda3 100644
--- a/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java
+++ b/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java
@@ -2,6 +2,7 @@
 
 import com.ericbouchut.learndev.common.config.CacheConfig;
 import org.commonmark.Extension;
+import org.commonmark.ext.gfm.alerts.AlertsExtension;
 import org.commonmark.ext.gfm.tables.TablesExtension;
 import org.commonmark.node.Heading;
 import org.commonmark.node.Node;
@@ -11,6 +12,8 @@
 import org.commonmark.renderer.html.HtmlRenderer;
 import org.commonmark.renderer.html.HtmlWriter;
 import org.jsoup.Jsoup;
+import org.jsoup.nodes.Document;
+import org.jsoup.nodes.Element;
 import org.jsoup.safety.Safelist;
 import org.springframework.cache.annotation.Cacheable;
 import org.springframework.stereotype.Service;
@@ -22,6 +25,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.regex.Pattern;
 
 /**
  * Converts lesson Markdown to HTML that is safe to serve.
@@ -39,13 +43,64 @@
 public class MarkdownRenderer {
 
     // The class attribute on code keeps CommonMark's language-* hints
-    // (```java fences) available to a future syntax highlighter.
+    // (```java fences) available to a future syntax highlighter. The div/p
+    // class and data-alert-type attributes exist only for alerts, and
+    // stripUnknownAlertClasses() rejects every value the alert renderer
+    // does not emit, so raw HTML in a lesson cannot borrow site classes.
     private static final Safelist SAFELIST = Safelist.relaxed()
-            .addAttributes("code", "class");
+            .addAttributes("code", "class")
+            .addAttributes("div", "class", "data-alert-type")
+            .addAttributes("p", "class");
 
-    // GFM pipe tables, added on demand as ADR-0013 planned; the sanitizer
-    // allowlist already lets table markup through (Safelist.relaxed).
-    private static final List<Extension> EXTENSIONS = List.of(TablesExtension.create());
+    private static final Pattern ALERT_DIV_CLASS =
+            Pattern.compile("^markdown-alert markdown-alert-[a-z]+$");
+    private static final Pattern ALERT_TYPE_VALUE = Pattern.compile("^[a-z]+$");
+
+    /**
+     * Alert types accepted in lessons: the five GFM types keep their GitHub
+     * identity (IMPORTANT and CAUTION stay standalone), and the rest of the
+     * Obsidian callout set joins them, aliases included, each with its
+     * default title.
+     */
+    private static final Map<String, String> ALERT_TYPES = Map.ofEntries(
+            Map.entry("NOTE", "Note"),
+            Map.entry("TIP", "Tip"),
+            Map.entry("IMPORTANT", "Important"),
+            Map.entry("WARNING", "Warning"),
+            Map.entry("CAUTION", "Caution"),
+            Map.entry("ABSTRACT", "Abstract"),
+            Map.entry("SUMMARY", "Summary"),
+            Map.entry("TLDR", "TL;DR"),
+            Map.entry("INFO", "Info"),
+            Map.entry("TODO", "Todo"),
+            Map.entry("HINT", "Hint"),
+            Map.entry("SUCCESS", "Success"),
+            Map.entry("CHECK", "Check"),
+            Map.entry("DONE", "Done"),
+            Map.entry("QUESTION", "Question"),
+            Map.entry("HELP", "Help"),
+            Map.entry("FAQ", "FAQ"),
+            Map.entry("ATTENTION", "Attention"),
+            Map.entry("FAILURE", "Failure"),
+            Map.entry("FAIL", "Fail"),
+            Map.entry("MISSING", "Missing"),
+            Map.entry("DANGER", "Danger"),
+            Map.entry("ERROR", "Error"),
+            Map.entry("BUG", "Bug"),
+            Map.entry("EXAMPLE", "Example"),
+            Map.entry("QUOTE", "Quote"),
+            Map.entry("CITE", "Cite"));
+
+    // GFM pipe tables and alerts, added on demand as ADR-0013 planned; the
+    // sanitizer allowlist lets table markup through (Safelist.relaxed) and
+    // is extended above for the alert markup.
+    private static final List<Extension> EXTENSIONS = List.of(
+            TablesExtension.create(),
+            AlertsExtension.builder()
+                    .setAllowedTypes(ALERT_TYPES)
+                    .allowCustomTitles(true)
+                    .allowNestedAlerts(true)
+                    .build());
 
     private final Parser parser = Parser.builder()
             .extensions(EXTENSIONS)
@@ -62,7 +117,33 @@ public String render(String markdown) {
             return "";
         }
         String html = renderer.render(parser.parse(markdown));
-        return Jsoup.clean(html, SAFELIST);
+        return stripUnknownAlertClasses(Jsoup.clean(html, SAFELIST));
+    }
+
+    /**
+     * Second sanitization pass: the allowlist admits {@code class} on
+     * {@code div}/{@code p} so alerts stay styleable, but only the exact
+     * values the alert renderer emits may survive. Anything else (for
+     * example raw HTML trying to wear a site class like {@code alert} or
+     * {@code site-header}) is stripped.
+     */
+    private static String stripUnknownAlertClasses(String html) {
+        Document doc = Jsoup.parseBodyFragment(html);
+        doc.outputSettings().prettyPrint(false);
+        for (Element div : doc.select("div[class], div[data-alert-type]")) {
+            if (!ALERT_DIV_CLASS.matcher(div.className()).matches()) {
+                div.removeAttr("class");
+            }
+            if (!ALERT_TYPE_VALUE.matcher(div.attr("data-alert-type")).matches()) {
+                div.removeAttr("data-alert-type");
+            }
+        }
+        for (Element p : doc.select("p[class]")) {
+            if (!"markdown-alert-title".equals(p.className())) {
+                p.removeAttr("class");
+            }
+        }
+        return doc.body().html();
     }
 
     /**
diff --git a/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java b/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java
index 75c4165..a2c237e 100644
--- a/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java
+++ b/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java
@@ -110,6 +110,88 @@ void renders_gfm_pipe_tables_as_html_tables() {
         assertThat(html).contains("<td>Array</td>");
     }
 
+    @Test
+    void renders_gfm_alerts_with_type_class_and_default_title() {
+        // Arrange (Given): a GFM alert, uppercase marker as GitHub writes it
+        String markdown = "> [!NOTE]\n> Take notes.";
+
+        // Act (When)
+        String html = markdownRenderer.render(markdown);
+
+        // Assert (Then): the typed div and the default title survive
+        // rendering and both sanitization passes
+        assertThat(html).contains("markdown-alert markdown-alert-note");
+        assertThat(html).contains("<p class=\"markdown-alert-title\">Note</p>");
+        assertThat(html).contains("Take notes.");
+    }
+
+    @Test
+    void renders_obsidian_callout_types_and_aliases_case_insensitively() {
+        // Arrange (Given): an Obsidian-only type and a lowercase alias whose
+        // default title is not just the capitalized marker
+        String markdown = "> [!bug]\n> Off by one.\n\n> [!tldr]\n> Short version.";
+
+        // Act (When)
+        String html = markdownRenderer.render(markdown);
+
+        // Assert (Then): both resolve to their registered type and title
+        assertThat(html).contains("markdown-alert markdown-alert-bug");
+        assertThat(html).contains("<p class=\"markdown-alert-title\">Bug</p>");
+        assertThat(html).contains("markdown-alert markdown-alert-tldr");
+        assertThat(html).contains("<p class=\"markdown-alert-title\">TL;DR</p>");
+    }
+
+    @Test
+    void renders_custom_alert_titles_with_inline_formatting() {
+        // Arrange (Given): a title after the marker (allowCustomTitles)
+        String markdown = "> [!tip] Use **bold** wisely\n> Body text.";
+
+        // Act (When)
+        String html = markdownRenderer.render(markdown);
+
+        // Assert (Then): the custom title replaces the default and its
+        // inline Markdown is rendered
+        assertThat(html).contains("markdown-alert markdown-alert-tip");
+        assertThat(html).contains("Use <strong>bold</strong> wisely");
+        assertThat(html).doesNotContain(">Tip</p>");
+    }
+
+    @Test
+    void renders_alerts_nested_inside_alerts() {
+        // Arrange (Given): a warning inside a note (allowNestedAlerts);
+        // without nesting the inner marker would degrade to literal text
+        String markdown = "> [!note]\n> Outer.\n> > [!warning]\n> > Inner.";
+
+        // Act (When)
+        String html = markdownRenderer.render(markdown);
+
+        // Assert (Then): both alerts materialize as typed divs
+        assertThat(html).contains("markdown-alert markdown-alert-note");
+        assertThat(html).contains("markdown-alert markdown-alert-warning");
+        assertThat(html).doesNotContain("[!warning]");
+    }
+
+    @Test
+    void strips_class_spoofing_while_alert_classes_survive() {
+        // Arrange (Given): raw HTML trying to wear site classes next to a
+        // genuine alert; the allowlist admits class on div/p, so only the
+        // second sanitization pass stands between this and the stylesheet
+        String markdown = "<div class=\"site-header\">spoof</div>\n\n"
+                + "<p class=\"alert alert--error\">spoof</p>\n\n"
+                + "<div data-alert-type=\"NOT_A_TYPE\">spoof</div>\n\n"
+                + "> [!note]\n> Legit.";
+
+        // Act (When)
+        String html = markdownRenderer.render(markdown);
+
+        // Assert (Then): spoofed values are stripped, alert markup is kept
+        assertThat(html).doesNotContain("site-header");
+        assertThat(html).doesNotContain("alert--error");
+        assertThat(html).doesNotContain("NOT_A_TYPE");
+        assertThat(html).contains("markdown-alert markdown-alert-note");
+        assertThat(html).contains("<p class=\"markdown-alert-title\">Note</p>");
+    }
+
     @Test
     void blank_content_renders_to_an_empty_string() {
         assertThat(markdownRenderer.render("")).isEmpty();

From ed449aa397cdfdbbf39f2b0c04eb2a7e5824e211 Mon Sep 17 00:00:00 2001
From: Eric Bouchut <ebouchut@gmail.com>
Date: Tue, 28 Jul 2026 10:04:58 +0200
Subject: [PATCH 7/8] feat(frontend): Style lesson alerts with octicon icons

The alert markup from the previous commit carried classes with no
styles behind them. The lesson-content section of base.css now styles
markdown-alert blocks: an accent border and title color per type
family, driven by the existing theme tokens so both themes work, and
an Octicon per type (the icon set GitHub uses for alerts, matched
against Obsidian's icon semantics).

Icons ship as mask-image data URIs painted with currentColor, so the
sanitized HTML never needs to carry SVG markup and the sanitizer
allowlist stays free of SVG tags. Nested alerts inset with a margin
and swap to the page background to stay visually distinct from their
parent. All 27 registered type classes are covered.

Fixes #116
---
 src/main/resources/static/css/base.css | 130 +++++++++++++++++++++++++
 1 file changed, 130 insertions(+)

diff --git a/src/main/resources/static/css/base.css b/src/main/resources/static/css/base.css
index daa250e..4e016a5 100644
--- a/src/main/resources/static/css/base.css
+++ b/src/main/resources/static/css/base.css
@@ -672,3 +672,133 @@ textarea.form__input {
   border-top: 1px solid var(--color-border);
   margin: var(--space-5) 0;
 }
+
+/* Alerts (GFM/Obsidian callouts) inside lesson content. Accent colors and
+   title come from CSS; icons are Octicons inlined as mask data URIs so the
+   sanitized HTML never needs to carry SVG markup. */
+
+.lesson-content .markdown-alert {
+  margin: 0 0 var(--space-3);
+  padding: var(--space-2) var(--space-4);
+  border-left: 4px solid var(--alert-accent, var(--color-border));
+  border-radius: var(--radius-sm);
+  background: var(--color-surface);
+}
+
+.lesson-content .markdown-alert-title {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  font-family: var(--font-display);
+  font-weight: 600;
+  /* Pulled 30% toward the text color: several raw accents sit just under
+     the 4.5:1 contrast floor (WCAG 1.4.3, RGAA 3.2) on the surface
+     background in the light theme; mixing toward the theme's text color
+     darkens them there and lightens them in the dark theme. */
+  color: color-mix(in srgb,
+      var(--alert-accent, var(--color-text)) 70%, var(--color-text));
+  margin-bottom: var(--space-2);
+}
+
+.lesson-content .markdown-alert-title::before {
+  content: "";
+  width: 1em;
+  height: 1em;
+  flex: none;
+  background-color: currentColor;
+  -webkit-mask: var(--alert-icon) center / contain no-repeat;
+  mask: var(--alert-icon) center / contain no-repeat;
+}
+
+/* Nested alerts sit flush inside their parent. */
+.lesson-content .markdown-alert .markdown-alert {
+  margin-top: var(--space-2);
+  background: var(--color-bg);
+}
+
+.lesson-content .markdown-alert-note {
+  --alert-accent: var(--color-link);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-info {
+  --alert-accent: var(--color-link);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-todo {
+  --alert-accent: var(--color-link);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M2.5 1.75v11.5c0 .138.112.25.25.25h3.17a.75.75 0 0 1 0 1.5H2.75A1.75 1.75 0 0 1 1 13.25V1.75C1 .784 1.784 0 2.75 0h8.5C12.216 0 13 .784 13 1.75v7.736a.75.75 0 0 1-1.5 0V1.75a.25.25 0 0 0-.25-.25h-8.5a.25.25 0 0 0-.25.25Zm13.274 9.537v-.001l-4.557 4.45a.75.75 0 0 1-1.055-.008l-1.943-1.95a.75.75 0 0 1 1.062-1.058l1.419 1.425 4.026-3.932a.75.75 0 1 1 1.048 1.074ZM4.75 4h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM4 7.75A.75.75 0 0 1 4.75 7h2a.75.75 0 0 1 0 1.5h-2A.75.75 0 0 1 4 7.75Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-abstract,
+.lesson-content .markdown-alert-summary,
+.lesson-content .markdown-alert-tldr {
+  --alert-accent: var(--color-focus);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M5.75 2.5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5Zm0 5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5Zm0 5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5ZM2 14a1 1 0 1 1 0-2 1 1 0 0 1 0 2Zm1-6a1 1 0 1 1-2 0 1 1 0 0 1 2 0ZM2 4a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-tip,
+.lesson-content .markdown-alert-hint {
+  --alert-accent: var(--color-success);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-important {
+  --alert-accent: var(--color-primary);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-success,
+.lesson-content .markdown-alert-check,
+.lesson-content .markdown-alert-done {
+  --alert-accent: var(--color-success);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm1.5 0a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm10.28-1.72-4.5 4.5a.75.75 0 0 1-1.06 0l-2-2a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018l1.47 1.47 3.97-3.97a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-question,
+.lesson-content .markdown-alert-help,
+.lesson-content .markdown-alert-faq {
+  --alert-accent: var(--color-warning);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.92 6.085h.001a.749.749 0 1 1-1.342-.67c.169-.339.436-.701.849-.977C6.845 4.16 7.369 4 8 4a2.756 2.756 0 0 1 1.637.525c.503.377.863.965.863 1.725 0 .448-.115.83-.329 1.15-.205.307-.47.513-.692.662-.109.072-.22.138-.313.195l-.006.004a6.24 6.24 0 0 0-.26.16.952.952 0 0 0-.276.245.75.75 0 0 1-1.248-.832c.184-.264.42-.489.692-.661.103-.067.207-.132.313-.195l.007-.004c.1-.061.182-.11.258-.161a.969.969 0 0 0 .277-.245C8.96 6.514 9 6.427 9 6.25a.612.612 0 0 0-.262-.525A1.27 1.27 0 0 0 8 5.5c-.369 0-.595.09-.74.187a1.01 1.01 0 0 0-.34.398ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-warning,
+.lesson-content .markdown-alert-attention {
+  --alert-accent: var(--color-warning);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-caution {
+  --alert-accent: var(--color-error);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-failure,
+.lesson-content .markdown-alert-fail,
+.lesson-content .markdown-alert-missing {
+  --alert-accent: var(--color-error);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M2.344 2.343h-.001a8 8 0 0 1 11.314 11.314A8.002 8.002 0 0 1 .234 10.089a8 8 0 0 1 2.11-7.746Zm1.06 10.253a6.5 6.5 0 1 0 9.108-9.275 6.5 6.5 0 0 0-9.108 9.275ZM6.03 4.97 8 6.94l1.97-1.97a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l1.97 1.97a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-1.97 1.97a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L6.94 8 4.97 6.03a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-danger,
+.lesson-content .markdown-alert-error {
+  --alert-accent: var(--color-error);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M9.504.43a1.516 1.516 0 0 1 2.437 1.713L10.415 5.5h2.123c1.57 0 2.346 1.909 1.22 3.004l-7.34 7.142a1.249 1.249 0 0 1-.871.354h-.302a1.25 1.25 0 0 1-1.157-1.723L5.633 10.5H3.462c-1.57 0-2.346-1.909-1.22-3.004L9.503.429Zm1.047 1.074L3.286 8.571A.25.25 0 0 0 3.462 9H6.75a.75.75 0 0 1 .694 1.034l-1.713 4.188 6.982-6.793A.25.25 0 0 0 12.538 7H9.25a.75.75 0 0 1-.683-1.06l2.008-4.418.003-.006a.036.036 0 0 0-.004-.009l-.006-.006-.008-.001c-.003 0-.006.002-.009.004Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-bug {
+  --alert-accent: var(--color-error);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M4.72.22a.75.75 0 0 1 1.06 0l1 .999a3.488 3.488 0 0 1 2.441 0l.999-1a.748.748 0 0 1 1.265.332.75.75 0 0 1-.205.729l-.775.776c.616.63.995 1.493.995 2.444v.327c0 .1-.009.197-.025.292.408.14.764.392 1.029.722l1.968-.787a.75.75 0 0 1 .556 1.392L13 7.258V9h2.25a.75.75 0 0 1 0 1.5H13v.5c0 .409-.049.806-.141 1.186l2.17.868a.75.75 0 0 1-.557 1.392l-2.184-.873A4.997 4.997 0 0 1 8 16a4.997 4.997 0 0 1-4.288-2.427l-2.183.873a.75.75 0 0 1-.558-1.392l2.17-.868A5.036 5.036 0 0 1 3 11v-.5H.75a.75.75 0 0 1 0-1.5H3V7.258L.971 6.446a.75.75 0 0 1 .558-1.392l1.967.787c.265-.33.62-.583 1.03-.722a1.677 1.677 0 0 1-.026-.292V4.5c0-.951.38-1.814.995-2.444L4.72 1.28a.75.75 0 0 1 0-1.06Zm.53 6.28a.75.75 0 0 0-.75.75V11a3.5 3.5 0 1 0 7 0V7.25a.75.75 0 0 0-.75-.75ZM6.173 5h3.654A.172.172 0 0 0 10 4.827V4.5a2 2 0 1 0-4 0v.327c0 .096.077.173.173.173Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-example {
+  --alert-accent: var(--color-primary);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M5 5.782V2.5h-.25a.75.75 0 0 1 0-1.5h6.5a.75.75 0 0 1 0 1.5H11v3.282l3.666 5.76C15.619 13.04 14.543 15 12.767 15H3.233c-1.776 0-2.852-1.96-1.899-3.458Zm-2.4 6.565a.75.75 0 0 0 .633 1.153h9.534a.75.75 0 0 0 .633-1.153L12.225 10.5h-8.45ZM9.5 2.5h-3V6c0 .143-.04.283-.117.403L4.73 9h6.54L9.617 6.403A.746.746 0 0 1 9.5 6Z%22%2F%3E%3C%2Fsvg%3E");
+}
+
+.lesson-content .markdown-alert-quote,
+.lesson-content .markdown-alert-cite {
+  --alert-accent: var(--color-text-muted);
+  --alert-icon: url("data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22 width%3D%2216%22 height%3D%2216%22 viewBox%3D%220 0 16 16%22%3E%3Cpath d%3D%22M1.75 2.5h10.5a.75.75 0 0 1 0 1.5H1.75a.75.75 0 0 1 0-1.5Zm4 5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5Zm0 5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5ZM2.5 7.75v6a.75.75 0 0 1-1.5 0v-6a.75.75 0 0 1 1.5 0Z%22%2F%3E%3C%2Fsvg%3E");
+}

From 945631aef8e4a4cf6dfa50a327e37213717edd60 Mon Sep 17 00:00:00 2001
From: Eric Bouchut <ebouchut@gmail.com>
Date: Tue, 28 Jul 2026 10:08:38 +0200
Subject: [PATCH 8/8] fix(markdown): Skip a leading heading duplicating the
 lesson title

A lesson whose Markdown starts with a level-1 heading equal to the
lesson title rendered the same text twice: the page h1 (the title from
the database) followed by an identical h2, the authored heading after
ADR-0014's demotion.

MarkdownRenderer gains a pure static, stripLeadingTitleHeading, that
drops the first non-blank heading when it is a level-1 ATX heading
(closing hashes tolerated) or a setext heading whose text equals the
lesson title, trimmed and case-insensitive. The lesson route applies
it before render() so the renderer stays cacheable by exact input and
the stored Markdown is never modified. A heading with different text,
or any deeper level, is kept as authored.

The lesson form now hints that the page already shows the title, and
ADR-0014 records the behavior as an amendment.

Fixes #117
---
 ...e-markdown-headings-in-lesson-rendering.md |  6 ++
 .../learndev/course/CourseController.java     | 12 ++-
 .../learndev/course/MarkdownRenderer.java     | 49 +++++++++++
 .../templates/instructor/lesson-form.html     |  2 +
 .../learndev/course/MarkdownRendererTest.java | 81 +++++++++++++++++++
 5 files changed, 146 insertions(+), 4 deletions(-)

diff --git a/docs/adr/0014-demote-markdown-headings-in-lesson-rendering.md b/docs/adr/0014-demote-markdown-headings-in-lesson-rendering.md
index 709aab4..b510b4b 100644
--- a/docs/adr/0014-demote-markdown-headings-in-lesson-rendering.md
+++ b/docs/adr/0014-demote-markdown-headings-in-lesson-rendering.md
@@ -55,6 +55,12 @@ audits exist to catch.
 - Trade-off: the rendered HTML no longer matches what a generic CommonMark
   renderer would produce for the same source (a surprise when comparing with
   an external preview)
+- Amendment (2026-07-28, issue #117): demotion turns the common habit of
+  starting a document with its own title into an `h2` that duplicates the
+  page `h1`, so the lesson route now strips a leading level-1 heading whose
+  text equals the lesson title before rendering
+  (`MarkdownRenderer.stripLeadingTitleHeading`); the stored Markdown is
+  untouched
 
 ## Pros and Cons of the Options
 
diff --git a/src/main/java/com/ericbouchut/learndev/course/CourseController.java b/src/main/java/com/ericbouchut/learndev/course/CourseController.java
index 80d88cb..3c31456 100644
--- a/src/main/java/com/ericbouchut/learndev/course/CourseController.java
+++ b/src/main/java/com/ericbouchut/learndev/course/CourseController.java
@@ -122,9 +122,11 @@ public String drop(@PathVariable Long courseId, Principal principal) {
     /**
      * Display one published lesson to an enrolled student, with the lesson
      * Markdown rendered to sanitized HTML and previous/next links in
-     * reading order. A student who is not actively enrolled is sent back to
-     * the course page with an {@code enroll-required} hint instead of a 403:
-     * the Register button is right there.
+     * reading order. A leading heading that repeats the lesson title is
+     * skipped: the page already renders the title as its {@code h1}. A
+     * student who is not actively enrolled is sent back to the course page
+     * with an {@code enroll-required} hint instead of a 403: the Register
+     * button is right there.
      *
      * @param courseId  the course the lesson belongs to
      * @param lessonId  the lesson to read
@@ -153,7 +155,9 @@ public String lesson(
         int index = indexOf(lessons, lesson);
         model.addAttribute("course", course);
         model.addAttribute("lesson", lesson);
-        model.addAttribute("contentHtml", markdownRenderer.render(lesson.getContentMarkdown()));
+        model.addAttribute("contentHtml", markdownRenderer.render(
+                MarkdownRenderer.stripLeadingTitleHeading(
+                        lesson.getContentMarkdown(), lesson.getTitle())));
         model.addAttribute("previousLesson", index > 0 ? lessons.get(index - 1) : null);
         model.addAttribute("nextLesson",
                 index < lessons.size() - 1 ? lessons.get(index + 1) : null);
diff --git a/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java b/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java
index 45feda3..08de0d3 100644
--- a/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java
+++ b/src/main/java/com/ericbouchut/learndev/course/MarkdownRenderer.java
@@ -21,10 +21,12 @@
 import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
+import java.util.Arrays;
 import java.util.HexFormat;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 /**
@@ -56,6 +58,14 @@ public class MarkdownRenderer {
             Pattern.compile("^markdown-alert markdown-alert-[a-z]+$");
     private static final Pattern ALERT_TYPE_VALUE = Pattern.compile("^[a-z]+$");
 
+    // A level-1 ATX heading per CommonMark: up to 3 leading spaces, one #,
+    // whitespace, the text, then an optional closing run of #s that only
+    // counts when preceded by whitespace.
+    private static final Pattern LEADING_ATX_TITLE =
+            Pattern.compile("^ {0,3}#\\s+(.*?)(?:\\s+#+)?\\s*$");
+    private static final Pattern SETEXT_H1_UNDERLINE =
+            Pattern.compile("^ {0,3}=+\\s*$");
+
     /**
      * Alert types accepted in lessons: the five GFM types keep their GitHub
      * identity (IMPORTANT and CAUTION stay standalone), and the rest of the
@@ -146,6 +156,45 @@ private static String stripUnknownAlertClasses(String html) {
         return doc.body().html();
     }
 
+    /**
+     * Drops a leading level-1 heading whose text repeats the lesson title,
+     * so the common habit of starting a document with its title does not
+     * render as an {@code h2} duplicating the page {@code h1} (see
+     * ADR-0014). Handles the ATX form ({@code # Title}, closing {@code #}s
+     * tolerated) and the setext form ({@code Title} underlined with
+     * {@code =}); the match is trimmed and case-insensitive. Callers apply
+     * this BEFORE {@link #render(String)} so the render cache stays keyed
+     * by the exact rendered input; the stored Markdown is never modified.
+     */
+    public static String stripLeadingTitleHeading(String markdown, String title) {
+        if (markdown == null || title == null || title.isBlank()) {
+            return markdown;
+        }
+        String[] lines = markdown.split("\n", -1);
+        int first = 0;
+        while (first < lines.length && lines[first].isBlank()) {
+            first++;
+        }
+        if (first == lines.length) {
+            return markdown;
+        }
+        String wanted = title.strip();
+        Matcher atx = LEADING_ATX_TITLE.matcher(lines[first]);
+        if (atx.matches() && atx.group(1).strip().equalsIgnoreCase(wanted)) {
+            return joinFrom(lines, first + 1);
+        }
+        if (first + 1 < lines.length
+                && lines[first].strip().equalsIgnoreCase(wanted)
+                && SETEXT_H1_UNDERLINE.matcher(lines[first + 1]).matches()) {
+            return joinFrom(lines, first + 2);
+        }
+        return markdown;
+    }
+
+    private static String joinFrom(String[] lines, int from) {
+        return String.join("\n", Arrays.asList(lines).subList(from, lines.length));
+    }
+
     /**
      * Cache key: SHA-256 of the source. Content-addressed, so edited content
      * is a new key and stale entries cannot exist; the fixed-size key also
diff --git a/src/main/resources/templates/instructor/lesson-form.html b/src/main/resources/templates/instructor/lesson-form.html
index 460b745..e503877 100644
--- a/src/main/resources/templates/instructor/lesson-form.html
+++ b/src/main/resources/templates/instructor/lesson-form.html
@@ -38,6 +38,8 @@
         <label class="form__label" for="contentMarkdown">Content (Markdown)</label>
         <span class="form__hint" id="contentMarkdown-hint">
           Markdown is rendered and sanitized before students see it.
+          The lesson page already shows the title above the content,
+          so there is no need to repeat it as a first heading.
         </span>
         <textarea class="form__input" th:field="*{contentMarkdown}" rows="14"
                   aria-describedby="contentMarkdown-hint"></textarea>
diff --git a/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java b/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java
index a2c237e..910791b 100644
--- a/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java
+++ b/src/test/java/com/ericbouchut/learndev/course/MarkdownRendererTest.java
@@ -197,4 +197,85 @@ void blank_content_renders_to_an_empty_string() {
         assertThat(markdownRenderer.render("")).isEmpty();
         assertThat(markdownRenderer.render("   ")).isEmpty();
     }
+
+    @Test
+    void strips_a_leading_atx_heading_matching_the_lesson_title() {
+        // Arrange (Given): the common habit of repeating the title on top,
+        // with leading blank lines, odd spacing, and a closing hash run
+        String markdown = "\n\n#  Java Basics  ##\n\nFirst paragraph.";
+
+        // Act (When)
+        String stripped = MarkdownRenderer.stripLeadingTitleHeading(markdown, "Java Basics");
+
+        // Assert (Then): only the duplicate heading is gone
+        assertThat(stripped).doesNotContain("Java Basics");
+        assertThat(stripped).contains("First paragraph.");
+    }
+
+    @Test
+    void strips_a_matching_title_heading_case_insensitively() {
+        String markdown = "# JAVA BASICS\nBody.";
+
+        String stripped = MarkdownRenderer.stripLeadingTitleHeading(markdown, "Java Basics");
+
+        assertThat(stripped).isEqualTo("Body.");
+    }
+
+    @Test
+    void strips_a_leading_setext_heading_matching_the_lesson_title() {
+        // Arrange (Given): the setext form, title underlined with equals
+        String markdown = "Java Basics\n====\n\nBody.";
+
+        // Act (When)
+        String stripped = MarkdownRenderer.stripLeadingTitleHeading(markdown, "Java Basics");
+
+        // Assert (Then)
+        assertThat(stripped).isEqualTo("\nBody.");
+    }
+
+    @Test
+    void keeps_a_leading_heading_with_a_different_text() {
+        // Arrange (Given): a real first heading, not a title duplicate
+        String markdown = "# Introduction\nBody.";
+
+        // Act (When)
+        String stripped = MarkdownRenderer.stripLeadingTitleHeading(markdown, "Java Basics");
+
+        // Assert (Then): untouched, the author meant this heading
+        assertThat(stripped).isEqualTo(markdown);
+    }
+
+    @Test
+    void keeps_deeper_headings_even_when_they_match_the_title() {
+        // Arrange (Given): only a level-1 heading duplicates the page h1
+        String markdown = "## Java Basics\nBody.";
+
+        // Act (When)
+        String stripped = MarkdownRenderer.stripLeadingTitleHeading(markdown, "Java Basics");
+
+        // Assert (Then)
+        assertThat(stripped).isEqualTo(markdown);
+    }
+
+    @Test
+    void strips_the_title_heading_despite_windows_line_endings() {
+        // Arrange (Given): textarea submissions carry \r\n line endings,
+        // so this is what stored lesson content actually looks like
+        String markdown = "# Java Basics\r\n\r\nBody.";
+
+        // Act (When)
+        String stripped = MarkdownRenderer.stripLeadingTitleHeading(markdown, "Java Basics");
+
+        // Assert (Then): the heading goes, the \r\n rhythm stays
+        assertThat(stripped).isEqualTo("\r\nBody.");
+    }
+
+    @Test
+    void title_stripping_tolerates_null_and_blank_input() {
+        assertThat(MarkdownRenderer.stripLeadingTitleHeading(null, "T")).isNull();
+        assertThat(MarkdownRenderer.stripLeadingTitleHeading("# T\nBody.", null))
+                .isEqualTo("# T\nBody.");
+        assertThat(MarkdownRenderer.stripLeadingTitleHeading("# T\nBody.", "  "))
+                .isEqualTo("# T\nBody.");
+    }
 }