Standardize code blocks on fenced ```lang + markdownlint CI gate (#99)#121
Merged
Conversation
) 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)
{% highlight LANG %}…{% endhighlight %}→ fenced```langblocks. Language tokens normalized to lowercase;cppfor all Arduino/ESP32 sketches (wasC/C++);JavaScript→javascript,HTML→html,CSS→css, etc.```block gets a language:textfor terminal/program output, file trees, and format examples;bashfor shell commands. (Satisfies MD040 site-wide.)raw/endrawso 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.jsoncso the gate only checks code-block rules (not the many unrelated style nits the older content predates).code-blocksjob incontent-lint.ymlrunningmarkdownlint-cli -c(which replaces config; cli2 merges the editor config back 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).markdownlint-cli@0.48.0 -c .markdownlint-code.jsonc).cppblocks; commented blocks stay hidden; literal Liquid in the LaTeX example renders verbatim; no leaked tags.🤖 Generated with Claude Code