Code Block Rendering

Identity

Field	Value
Block name	kevinbatdorf/code-block-pro
Free plugin	code-block-pro v1.28.0 (wordpress.org)
Theme pack	code-block-pro-wp-cbp-themes-pack-release-… v1.6.2 (paid)
Highlighter	Shiki v0.14.4 (VS Code engine, TextMate grammars)
Default theme	github-dark
Production path	/home/Dmg59ZFtKg6bIws1/id86net/public_html/wp-content/plugins/
Content standards	3. Content → Article Body Elements

What It Does

Every fenced code block in a documentation post is rendered as a Code Block Pro Gutenberg block. The highlighting is pre-rendered at sync time by Shiki — the same engine VS Code uses — so the saved post_content contains fully colored HTML with no client-side tokenizer and no CDN dependency. The plugin's front.js adds the copy button on top of the saved markup.

Pipeline

Markdown (```lang fence)
  -> sync.py (markdown2 with highlightjs-lang -> <pre><code class="lang language-lang">)
  -> tools/code_block_pro/blocks.py (transform_code_blocks)
      -> tools/code-block-pro/render.js (Shiki github-dark -> highlighted HTML)
      -> wp:kevinbatdorf/code-block-pro block comment + inner HTML
  -> wp-sync-bridge.php (wp_insert_post)
  -> frontend: WordPress outputs saved HTML; CBP front.js adds copy button

Why Gutenberg Blocks

Code Block Pro is a Gutenberg block plugin: it only renders code that exists as its own block markup (<!-- wp:kevinbatdorf/code-block-pro {...} -->). Posts generated from Markdown therefore carry the block markup in post_content. No editor session is ever involved — the Shiki HTML is generated by the local sync pipeline and stored directly.

Sync Tooling

File	Role
tools/code-block-pro/package.json	Pins shiki@0.14.4 (exact version, no caret)
tools/code-block-pro/render.js	Node renderer; reads {"language","code"} JSON lines on stdin, prints JSON-encoded Shiki HTML
tools/code_block_pro/blocks.py	Python block builder: transform_code_blocks(), build_block(), render_shiki_batch()
sync.py	Calls transform_code_blocks() on each document body during parse

Notes:

• Shiki resolves common aliases (js, sh, yml, md, txt, console, terminal, nginx, …) to real grammars. Unknown languages fall back to plaintext.
• Rendering is batched (one Node process per sync run) for speed.
• The block builder replicates the plugin's exact save() output, including the copy-button markup (code-block-pro-copy-button + hidden textarea) and attribute set, so the editor shows no "unexpected content" warning if a post is opened.
• fontFamily is left empty so the plugin's font loader stays idle (no extra font downloads).
• tools/ and node_modules/ are excluded from document collection and from Git.

Saved Block Format

The stored post_content for a Python block looks like:

<!-- wp:kevinbatdorf/code-block-pro {"code":"...","codeHTML":"<pre class=\"shiki github-dark\"...","language":"python","theme":"github-dark","copyButton":true,...} -->
<div class="wp-block-kevinbatdorf-code-block-pro" data-code-block-pro-font-family="" style="...">
  <span class="code-block-pro-copy-button">…textarea + svg…</span>
  <pre class="shiki github-dark" style="background-color: #24292e">…tokens…</pre>
</div>
<!-- /wp:kevinbatdorf/code-block-pro -->

The codeHTML attribute holds the full Shiki-highlighted HTML; the inner <pre class="shiki"> is what visitors see.

Deployment

• One-time install: code-block-pro (free) + the paid theme pack must both be active. The theme pack only adds extra editor themes; github-dark ships with the free plugin.
• Content migration: run sync.py --force to regenerate every post into the new block format. The existing hash-skip logic then keeps unchanged posts untouched on later runs.
• Node requirement: local only. The sync machine needs Node for Shiki; production does not (the block HTML is already stored).
• After renderer changes: touch tools/code-block-pro/render.js is not needed (no cache), but re-run sync.py --force so all posts pick up new markup.

Theme / Child Theme

• Prism CDN enqueues were removed from functions.php (no more jsdelivr dependency).
• css/article-content-v2.css scopes its pre/code rules with :not(.shiki):not(.code-block-pro-copy-button-pre) so the theme's navy block styling never overrides Shiki's GitHub Dark rendering.
• .wp-block-kevinbatdorf-code-block-pro pre.shiki gets a subtle border: 1px solid #30363d + border-radius: 8px from the theme.
• The theme's js/article-content.js skips Code Block Pro blocks when injecting its own copy button (pre.closest('.wp-block-kevinbatdorf-code-block-pro')), so CBP blocks show only the plugin's icon copy button — no duplicate "Copy" text label. css/article-content-v2.css also hides any stray .id86-copy-btn inside CBP blocks as a safety net.
• Dark mode (ID86 Dark Mode plugin) continues to work: Dark Reader re-tints the block's inline token colors automatically.

Verification

A browser check confirms each code post renders:

• .wp-block-kevinbatdorf-code-block-pro blocks present
• pre.shiki with colored token spans (Shiki github-dark)
• .code-block-pro-copy-button visible after front.js runs (copy source is the hidden textarea)
• No id86-copy-btn inside CBP blocks (theme copy button is skipped there)
• No prism.min.js / prism-autoloader on the page
• Dark mode toggle still present

Verified pages: python-cheat-sheet, git-cheat-sheet, docker-compose, plocate-cheat-sheet, styling-sample.