Skip to content

Standardize code-block formatting and enforce it in CI #99

Description

@jonfroehlich

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)
  • Fenced 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 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

  1. Fenced ``` blocks with a required language token (standard Markdown, native Rouge highlighting, copy-button friendly, avoids the endhighlight footgun). Migrate all `{% highlight %}` → fenced.
  2. 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.
  • Wire both into CI (depends on Evaluate moving to a GitHub Actions Jekyll deploy (enabler for V2.0) #98) so PRs fail on violations.
  • Document the convention in website-dev.md.

Tasks

Related: CI gate depends on the GitHub Actions pipeline in #98.

Metadata

Metadata

Assignees

No one assigned

    Labels

    code-examplesEmbedded source code, sketch/code links, .ino syncdocumentationImprovements or additions to documentationenhancementNew feature or requestinfrastructureBuild, deploy, CI, performance, toolingv2.0Targeted for the Version 2.0 release

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions