From c7c57d5cfc2cc5b3f88590e94bd9e49ccfc7ae9f Mon Sep 17 00:00:00 2001
From: Joaquim Costa <jscosta88@gmail.com>
Date: Tue, 7 Jul 2026 16:58:51 -0400
Subject: [PATCH 1/4] fix(tailwind-from-scratch): escape note attribute quotes
 correctly
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two lessons' <CodeDiff note="..."> attributes embedded a literal
`\"..."` inside a plain JSX string attribute. JSX plain-attribute
strings don't support backslash-escaping — the backslash is literal
and the following quote closes the attribute early, desyncing the
rest of the tag. Velite drops both lessons from the catalog as a
result (silent 404 at runtime).

Swap the inner double quotes for single quotes; no escaping needed.
Verified both lessons now compile via @mdx-js/mdx (matches the
Velite/apps-web toolchain).
---
 courses/tailwind-from-scratch/lessons/22-modu-sukuru/kea.mdx    | 2 +-
 .../tailwind-from-scratch/lessons/23-tailwind-cli-v4/kea.mdx    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/courses/tailwind-from-scratch/lessons/22-modu-sukuru/kea.mdx b/courses/tailwind-from-scratch/lessons/22-modu-sukuru/kea.mdx
index 98b8b46..1791abe 100644
--- a/courses/tailwind-from-scratch/lessons/22-modu-sukuru/kea.mdx
+++ b/courses/tailwind-from-scratch/lessons/22-modu-sukuru/kea.mdx
@@ -31,7 +31,7 @@ Na v3, bu konfigura dark mode na `tailwind.config.js`. Na v4 kel linha sumiu —
   lang="css"
   filename="di v3 config pa v4 @custom-variant"
   title="Dark mode: di v3 pa v4"
-  note="v3 ta pega `darkMode: 'class'` na JavaScript config; v4 ta uza `@custom-variant` na bu blok `<style type=\"text/tailwindcss\">`."
+  note="v3 ta pega `darkMode: 'class'` na JavaScript config; v4 ta uza `@custom-variant` na bu blok `<style type='text/tailwindcss'>`."
   diff={[
     { type: "del", t: "/* v3 — ka ta funsiona na v4 */" },
     { type: "del", t: "module.exports = {" },
diff --git a/courses/tailwind-from-scratch/lessons/23-tailwind-cli-v4/kea.mdx b/courses/tailwind-from-scratch/lessons/23-tailwind-cli-v4/kea.mdx
index fe2bfbf..c63af32 100644
--- a/courses/tailwind-from-scratch/lessons/23-tailwind-cli-v4/kea.mdx
+++ b/courses/tailwind-from-scratch/lessons/23-tailwind-cli-v4/kea.mdx
@@ -51,7 +51,7 @@ Si bo seguir tutoriais v3 antigu, bo ta odja outru workflow. **Kuazi tudu muda n
   lang="css"
   filename="input.css"
   title="Di trez `@tailwind` pa un `@import`"
-  note="Un só `@import \"tailwindcss\";` ta inkluí base, komponenti i utilidadis — ka ten más trez direktivas separadu."
+  note="Un só `@import 'tailwindcss';` ta inkluí base, komponenti i utilidadis — ka ten más trez direktivas separadu."
   diff={[
     { type: "del", t: '/* v3 — kaduku na v4 */' },
     { type: "del", t: '@tailwind base;' },

From ef1d00ddf3907e19646be9e2f13d8ce29ccf55f0 Mon Sep 17 00:00:00 2001
From: Joaquim Costa <jscosta88@gmail.com>
Date: Tue, 7 Jul 2026 17:35:37 -0400
Subject: [PATCH 2/4] ci(content): add MDX/JSX syntax validation gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a validate-mdx CI job that compiles every lesson MDX body via
@mdx-js/mdx (with remark-directive, matching apps/web's Velite config)
and fails the build on any parse error.

Nothing in this pipeline previously checked MDX syntax at all — the
publish-time checks (frontmatter, heading lint, sidecar YAML) never
parse the MDX body as JSX, and Velite (apps/web) only runs downstream,
disconnected from publish, where a bad lesson is silently dropped from
the catalog (404 at runtime) rather than failing anything.

This is defense-in-depth alongside the equivalent validate-mdx gate now
added to pipeline-app's publish flow (skola-claude-plugins) — that gate
catches it before the content even reaches this repo; this one catches
it for any direct push that bypasses that pipeline.
---
 .github/workflows/content-ci.yml | 24 +++++++++++++++
 scripts/check-mdx-syntax.mjs     | 52 ++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 scripts/check-mdx-syntax.mjs

diff --git a/.github/workflows/content-ci.yml b/.github/workflows/content-ci.yml
index 0b810f8..09ea7a2 100644
--- a/.github/workflows/content-ci.yml
+++ b/.github/workflows/content-ci.yml
@@ -91,6 +91,30 @@ jobs:
           fi
           echo "All touched artifacts updated their CHANGELOG.md."
 
+  # Validate every lesson MDX body actually compiles as MDX/JSX (mirrors the
+  # local `mdx-syntax` Lefthook hook). Catches parser-desyncing authoring
+  # mistakes — most commonly a backslash-escaped double quote inside a plain
+  # JSX attribute (e.g. note="...\"...") — which JSX doesn't treat as an
+  # escape. Without this, a malformed lesson lands on main clean and only
+  # fails later when apps/web runs Velite, which silently drops it from the
+  # catalog (404 at runtime) instead of failing the build. See PR #9
+  # (tailwind-from-scratch lessons 22 + 23).
+  validate-mdx:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install MDX compiler
+        run: npm install --no-save @mdx-js/mdx remark-directive
+
+      - name: Validate lesson MDX syntax
+        run: node scripts/check-mdx-syntax.mjs
+
   # Validate code samples can at least be parsed
   validate-code:
     runs-on: ubuntu-latest
diff --git a/scripts/check-mdx-syntax.mjs b/scripts/check-mdx-syntax.mjs
new file mode 100644
index 0000000..3f582c2
--- /dev/null
+++ b/scripts/check-mdx-syntax.mjs
@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// check-mdx-syntax.mjs — fail if any course lesson .mdx doesn't compile as MDX/JSX.
+//
+// Mirrors the existing `validate-code` job's py_compile/mvn-compile parse checks
+// (content-ci.yml), but for lesson MDX. Catches parser-desyncing authoring
+// mistakes — most commonly a backslash-escaped double quote inside a plain JSX
+// attribute (e.g. `note="...\"..."`), which JSX does NOT treat as an escape: the
+// `\` is literal, so the following `"` ends the attribute early and desyncs the
+// rest of the tag.
+//
+// Without this check a malformed lesson still lands on `main` clean, and only
+// fails later when apps/web runs Velite — which silently drops the lesson from
+// the catalog (404 at runtime) instead of failing the build. See PR #9
+// (tailwind-from-scratch lessons 22 + 23).
+//
+// Usage: node scripts/check-mdx-syntax.mjs
+// Requires @mdx-js/mdx + remark-directive to be installed (CI installs them
+// transiently; this repo has no package.json of its own).
+//
+// remarkDirective MUST be passed to compile() — it's the same plugin
+// apps/web's Velite config wires in (see apps/web/velite.config.ts). Without
+// it, a plain compile() misparses legitimate `:::callout{type=tip}` directive
+// blocks (the `{type=tip}` attribute shorthand isn't valid bare MDX/JS) and
+// throws a false positive on content Velite compiles just fine.
+import { compile } from "@mdx-js/mdx";
+import remarkDirective from "remark-directive";
+import { readFile } from "node:fs/promises";
+import { glob } from "node:fs/promises";
+
+function stripFrontmatter(content) {
+  return content.replace(/^---\n[\s\S]*?\n---\n?/, "");
+}
+
+let failures = 0;
+
+for await (const file of glob("courses/*/lessons/*/*.mdx")) {
+  const raw = await readFile(file, "utf8");
+  const body = stripFrontmatter(raw);
+  try {
+    await compile(body, { jsx: true, remarkPlugins: [remarkDirective] });
+  } catch (e) {
+    failures++;
+    console.error(`✖ ${file}`);
+    console.error(`  ${e.message.split("\n")[0]}`);
+  }
+}
+
+if (failures > 0) {
+  console.error(`\n${failures} lesson(s) failed MDX syntax validation.`);
+  process.exit(1);
+}
+console.log("All lesson MDX files compile cleanly.");

From 40aa7cbd54b87bc810f20ee0797bbdfafda2b02f Mon Sep 17 00:00:00 2001
From: Joaquim Costa <jscosta88@gmail.com>
Date: Tue, 7 Jul 2026 17:36:25 -0400
Subject: [PATCH 3/4] docs(tailwind-from-scratch): record CHANGELOG entry for
 the note-quote fix

Required by this repo's own changelog-guard gate (courses/*/** changes
must be recorded in that course's CHANGELOG.md).
---
 courses/tailwind-from-scratch/CHANGELOG.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/courses/tailwind-from-scratch/CHANGELOG.md b/courses/tailwind-from-scratch/CHANGELOG.md
index 1e3e096..a53ff5c 100644
--- a/courses/tailwind-from-scratch/CHANGELOG.md
+++ b/courses/tailwind-from-scratch/CHANGELOG.md
@@ -13,6 +13,9 @@ copy are recorded under their own dated heading.
 ### Changed
 - Removed `test_only: true` from `course.yaml`. User decision: it's fine to promote the course to production now — visibility will be gated via the admin portal instead of keeping the whole course out of the catalog. `code/m3-resort-brava` and the microlearn units remain outstanding and can be added in a follow-up publish without re-gating.
 
+### Fixed
+- Lessons `22-modu-sukuru` and `23-tailwind-cli-v4`: fixed a `<CodeDiff note="...">` attribute that embedded a backslash-escaped double quote (`\"`), which JSX plain-attribute strings don't support as an escape — it desynced the tag parser and Velite dropped both lessons from the catalog (404 at runtime). Swapped the inner quotes to single quotes; no meaning change. See deznode/skola-content#9.
+
 ## [2026-07-07] — publish
 
 ### Added

From 7b0079cdf10bf1c97720553c5ffc60400089ef54 Mon Sep 17 00:00:00 2001
From: Joaquim Costa <jscosta88@gmail.com>
Date: Tue, 7 Jul 2026 17:38:38 -0400
Subject: [PATCH 4/4] fix(ci): avoid fs.promises.glob (Node 22+ only) in
 check-mdx-syntax.mjs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI pins Node 20 (matching the rest of content-ci.yml), and
fs.promises.glob doesn't exist until Node 22 — the validate-mdx job
failed outright with a SyntaxError before it ever compiled a single
file. Replaced with a portable manual recursive directory walk.

Verified locally: still flags exactly the 2 known-bad lessons when
pointed at their pre-fix content, and reports clean against this
branch's fixed content.
---
 scripts/check-mdx-syntax.mjs | 37 +++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

diff --git a/scripts/check-mdx-syntax.mjs b/scripts/check-mdx-syntax.mjs
index 3f582c2..85ef74d 100644
--- a/scripts/check-mdx-syntax.mjs
+++ b/scripts/check-mdx-syntax.mjs
@@ -24,16 +24,47 @@
 // throws a false positive on content Velite compiles just fine.
 import { compile } from "@mdx-js/mdx";
 import remarkDirective from "remark-directive";
-import { readFile } from "node:fs/promises";
-import { glob } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
 
 function stripFrontmatter(content) {
   return content.replace(/^---\n[\s\S]*?\n---\n?/, "");
 }
 
+// Portable recursive walk for lesson MDX under courses/<slug>/lessons/<NN-slug>/*.mdx.
+// Avoids fs.promises.glob (Node 22+ only) so this runs on the Node 20 CI pins elsewhere.
+async function* findLessonMdx(root) {
+  let coursesEntries;
+  try {
+    coursesEntries = await readdir(path.join(root, "courses"), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const course of coursesEntries) {
+    if (!course.isDirectory()) continue;
+    const lessonsDir = path.join(root, "courses", course.name, "lessons");
+    let lessonDirs;
+    try {
+      lessonDirs = await readdir(lessonsDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const lesson of lessonDirs) {
+      if (!lesson.isDirectory()) continue;
+      const lessonPath = path.join(lessonsDir, lesson.name);
+      const files = await readdir(lessonPath, { withFileTypes: true });
+      for (const file of files) {
+        if (file.isFile() && file.name.endsWith(".mdx")) {
+          yield path.join(lessonPath, file.name);
+        }
+      }
+    }
+  }
+}
+
 let failures = 0;
 
-for await (const file of glob("courses/*/lessons/*/*.mdx")) {
+for await (const file of findLessonMdx(process.cwd())) {
   const raw = await readFile(file, "utf8");
   const body = stripFrontmatter(raw);
   try {