You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Code blocks across the textbook are inconsistent in both delimiter style and language tokens, which hurts rendering consistency, the copy-code button, and maintainability. Two delimiter systems coexist:
{% highlight C %} ×52, {% highlight C++ %} ×59, {% highlight cpp %} ×26, plus ~80 fenced cpp and a couple C fences — 3–4 tokens for one language
HTML ×14 vs html ×1
Latent bug: nearly every block closes with {% endhighlight C %} / {% endhighlight JavaScript %} etc. Jekyll's endhighlight takes no argument — tolerated today but non-standard/fragile.
Bare fences with no language (no syntax highlighting): communication/serial-intro.md (~10), plus serial-print, rgb-led-fade, led-blink3, inside-arduino, esp32-ide, advancedio/oled, and the signals pages.
Target convention already exists: the esp32 module converged on ```cpp.
Proposed standard
Fenced ``` blocks with a required language token (standard Markdown, native Rouge highlighting, copy-button friendly, avoids the endhighlight footgun). Migrate all `{% highlight %}` → fenced.
One token per language:cpp for all Arduino/ESP32 sketches (Rouge has no arduino lexer; cpp is correct/supported), plus javascript, python, html, css, json, bash.
Enforce in the build/test system
markdownlint built-ins: enable MD040 (fenced blocks must declare a language), MD046 (fenced, not indented), MD048 (``` not ~~~).
Custom scripts/lint_code_blocks.py for what markdownlint can't see: remaining {% highlight %} tags, variant/wrong language tokens (C/C++ → cpp), and the endhighlight LANG form.
Problem
Code blocks across the textbook are inconsistent in both delimiter style and language tokens, which hurts rendering consistency, the copy-code button, and maintainability. Two delimiter systems coexist:
{% highlight %}Liquid tags (older revised modules: arduino, communication, advancedio)blocks (newer esp32 work — uniformlycpp)Evidence (counts across
*.md, excluding_site/)Same language, multiple tokens — Arduino/ESP32 sketches (all C++) appear as:
{% highlight C %}×52,{% highlight C++ %}×59,{% highlight cpp %}×26, plus ~80 fencedcpp and a coupleC fences — 3–4 tokens for one languageHTML×14 vshtml×1Latent bug: nearly every block closes with
{% endhighlight C %}/{% endhighlight JavaScript %}etc. Jekyll'sendhighlighttakes no argument — tolerated today but non-standard/fragile.Bare fences with no language (no syntax highlighting):
communication/serial-intro.md(~10), plusserial-print,rgb-led-fade,led-blink3,inside-arduino,esp32-ide,advancedio/oled, and the signals pages.Target convention already exists: the esp32 module converged on ```cpp.
Proposed standard
endhighlightfootgun). Migrate all `{% highlight %}` → fenced.cppfor all Arduino/ESP32 sketches (Rouge has noarduinolexer;cppis correct/supported), plusjavascript,python,html,css,json,bash.Enforce in the build/test system
~~~).scripts/lint_code_blocks.pyfor what markdownlint can't see: remaining{% highlight %}tags, variant/wrong language tokens (C/C++→cpp), and theendhighlight LANGform.website-dev.md.Tasks
{% highlight %}→ fenced; normalize language tokens; remove bare fencesscripts/lint_code_blocks.pywebsite-dev.mdRelated: CI gate depends on the GitHub Actions pipeline in #98.