Skip to content

Standardize code blocks on fenced ```lang + markdownlint CI gate (#99)#121

Merged
jonfroehlich merged 1 commit into
mainfrom
feat/code-block-standardization
Jun 24, 2026
Merged

Standardize code blocks on fenced ```lang + markdownlint CI gate (#99)#121
jonfroehlich merged 1 commit into
mainfrom
feat/code-block-standardization

Conversation

@jonfroehlich

Copy link
Copy Markdown
Member

Closes #99.

What

Migrates the whole textbook from Jekyll {% highlight %} Liquid tags to fenced code blocks with a required language token, and adds a CI gate so the convention stays enforced.

Content (35 pages)

  • All {% highlight LANG %}{% endhighlight %} → fenced ```lang blocks. Language tokens normalized to lowercase; cpp for all Arduino/ESP32 sketches (was C/C++); JavaScriptjavascript, HTMLhtml, CSScss, etc.
  • Every previously-bare ``` block gets a language: text for terminal/program output, file trees, and format examples; bash for shell commands. (Satisfies MD040 site-wide.)
  • Fixed two commented-out example blocks whose opener migrated but whose inline closer didn't, which left unbalanced Liquid tags. The LaTeX doc example is now correctly wrapped in raw/endraw so it renders literally.

Gate

  • .markdownlint-code.jsonc — a scoped config (MD040 language-required, MD046 fenced-not-indented, MD048 backtick fences), intentionally separate from the editor .markdownlint.jsonc so the gate only checks code-block rules (not the many unrelated style nits the older content predates).
  • New code-blocks job in content-lint.yml running markdownlint-cli -c (which replaces config; cli2 merges the editor config back in).
  • Convention documented in website-dev.md "Code highlighting"; deliberate indented demos opt out with <!-- markdownlint-disable MD046 -->.

Why

Portability + tooling, and de-risking a future framework migration (#103) where Liquid tags would all need rewriting. {% highlight %} was legitimate when the site started — this is a forward move, not a fix.

Verification

  • bundle exec jekyll build — clean (Jekyll 4).
  • Scoped gate green across the repo (markdownlint-cli@0.48.0 -c .markdownlint-code.jsonc).
  • Spot-checked rendered HTML: 35 files with Rouge-highlighted cpp blocks; commented blocks stay hidden; literal Liquid in the LaTeX example renders verbatim; no leaked tags.

🤖 Generated with Claude Code

)

Migrate every Jekyll `{% highlight %}` block to a fenced code block with a
required language token, and enforce the convention in CI.

Content:
- Convert all `{% highlight LANG %}`...`{% endhighlight %}` to fenced ``` blocks
  across 35 lesson/doc pages. Normalize the language token to lowercase and use
  `cpp` for all Arduino/ESP32 sketches (was `C`/`C++`); JavaScript->javascript,
  HTML->html, CSS->css, etc.
- Give every previously-bare fenced block a language: `text` for terminal
  output / program output / file trees / format examples, `bash` for shell
  commands. Satisfies MD040 site-wide.
- Fix two commented-out example blocks whose opener migrated but whose inline
  closer (`... %} -->`, `{% endraw %}{% endhighlight %}`) did not, which left
  unbalanced Liquid tags; the LaTeX doc example is now correctly wrapped in
  raw/endraw so it renders literally.

Gate:
- Add .markdownlint-code.jsonc: a scoped config (MD040 language-required,
  MD046 fenced-not-indented, MD048 backtick fences) kept separate from the
  editor .markdownlint.jsonc so it only checks code-block rules.
- Add a `code-blocks` job to content-lint.yml running `markdownlint-cli -c`
  (replaces config; cli2 would merge the editor config back in).
- Document the convention and gate in website-dev.md "Code highlighting".

Rationale: portability + tooling, and de-risking a future framework migration
(#103) where Liquid tags would all need rewriting.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jonfroehlich jonfroehlich merged commit 71a9749 into main Jun 24, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Standardize code-block formatting and enforce it in CI

1 participant