[3.x] Render fenced code blocks through a composable Blade view

[emmadesilva]

Summary

Fenced code blocks were the last Markdown construct in Hyde still assembled by string surgery. A pre-processor rewrote // filepath: comments into <!-- HYDE[Filepath] --> marker comments, and a post-processor spliced the rendered label back into the finished HTML with a regex matching <pre><code class="language-…">.

That design set the feature's ceiling. The label could only ever be a fragment wedged inside the <code> element, because that was the only place a string replacement could reach. Anything else a code block might want — a copy button, a header bar, a collapsed state — had nowhere to live. The class even carried a @todo saying as much.

Code blocks now go through the same pipeline as terminal blocks: a CommonMark extension prepares each fenced node, and a renderer hands a typed view model to a publishable Blade view. The view owns everything around the code, so block chrome is a view change rather than a framework change.

The Torchlight constraint

The view is handed the finished <pre><code> markup rather than the raw code, which is what keeps Torchlight working.

Torchlight registers its own renderer for fenced code nodes and highlights through its API, so Hyde cannot render the code itself without replacing the highlighter. Instead Hyde's renderer registers above Torchlight's and asks the renderers below it for the markup, exactly as CommonMark's document renderer would, then wraps whatever comes back. Torchlight stays in charge when enabled, CommonMark's own renderer answers when it is not, and the view is told which one it got through $highlightedByTorchlight.

For the same reason the node stays a FencedCode rather than being replaced with a Hyde node the way terminal blocks are — a replaced node is a node Torchlight's renderer is never asked about. The label is resolved onto the node's data while the document is walked, and the renderer reads it back. That listener runs after the terminal transformer has claimed its nodes and before Torchlight collects the code it sends off, so the filepath comment is stripped from the code that gets highlighted.

New: setting the label on the fence

Labels can now also be set with a title="…" modifier, using the same attribute syntax as terminal block titles:

```php title="app/Models/Example.php"
echo 'Hello World!';
```

The existing comment syntax is unchanged and still works. When a block uses both, the modifier wins — it is the explicit, structured form, and it lives on the fence rather than in the code, so a block carrying both is almost certainly mid-migration. The comment is stripped from the code either way.

Hyde\Markdown\Extensions\CodeBlockViewModel is public, unlike the terminal one, since a code block is a thing projects reasonably want to render outside Markdown, and the view contract it pins down is the documented interface for anyone publishing the view.

What is actually breaking

Renaming the label view is the breaking change. components/filepath-label.blade.php → components/markdown/code-block-label.blade.php.

Published views take precedence over the framework's own, so a project that published and customized this view keeps using its copy after upgrading. The view's contract changed with the label's position, and a copy written for the old contract floats the label outside the code block when rendered in the new one — verified, it lands on the page background with the <pre> shrunk to make room. Keeping the name would have silently broken the layout of every site that customized it. Renaming leaves those copies unused instead, which costs the customization rather than the page. There is a regression test for exactly this.

The HTML changed, which is the part that reaches sites that never touched the feature. Blocks are wrapped in <div class="hyde-code-block relative">, with the label a sibling of the <pre>. Real impact on CSS that matched the old structure; hyde-code-block and hyde-code-block-label are stable hooks.

Not breaking

• CodeblockFilepathProcessor was removed. The processor list is hardcoded in an internal trait, so there was never a supported way to register it, and its two static methods only did anything as a pair handing <!-- HYDE[Filepath] --> markers to each other. Internal cleanup, filed under Removed — it is not in the upgrade guide, since there is no migration to do.
• Filepath comments are only read from the first line now. Closer to a fix: the first-line rule is what the docs always described, and the old pre-processor matched any line of the document only because it ran before parsing.

Torchlight is intact, and there are now tests proving it

The renderer delegating downward is the load-bearing part of this design, so it is now covered by tests that fake the Torchlight API and assert on what actually reaches it:

• Torchlight's markup (not CommonMark's) ends up inside the code block view.
• The filepath comment is stripped from the code before it is sent to the API — the request payload contains echo 'Hello World!';, not the comment.
• $highlightedByTorchlight is true under Torchlight and false without it.
• Terminal blocks are still never submitted to Torchlight.

Visual check

Rendered before and after with identical content, screenshotted headless, then pixel-diffed:

Comparison	Differing pixels	Diff bounding box
Plain code block, old vs new	0.35%	the label only
Torchlight code block, old vs new	0.38%	the label only

Everything outside the label's bounding box is pixel-identical — block position, size, spacing, paragraph flow, syntax colours. The label itself renders ~7% wider: it used to inherit <small>'s UA smaller size from the 14px <pre> (~11.6px), and now sets text-xs (12px) explicitly, because outside the <pre> there is no code font size to inherit. Happy to pin it to an arbitrary value if you would rather it be exact.

The label previously inherited --tw-prose-pre-code from the <pre> it lived in. Outside the <pre> it would have inherited the body text colour, leaving it dark-on-dark in light mode, so the shipped view sets that colour explicitly.

Testing

• New CodeBlocksTest (34 tests, including the Torchlight and stale-view regressions) and CodeBlockViewModelUnitTest (9 tests).
• ComposableMarkdownBlocksDocumentationTest gains a Code Blocks section, so every claim the rewritten masterclass page makes is asserted (103 tests).
• Full suite green, except a FeaturedImageUnitTest failure that reproduces on master and is unrelated to this change.
• HydeStan reports no errors.

Documentation

• docs/digging-deeper/composable-markdown-blocks.md — code blocks get their own section covering both label syntaxes, precedence, the view contract, class hooks, and a customization example. The pipeline and limitations sections are corrected.
• docs/digging-deeper/advanced-markdown.md — the title modifier, the precedence rule, and how to publish the views.
• UPGRADE.md, CHANGELOG.md, HYDEPHP_V3_PLANNING.md.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (ae6e160) to head (94aa177).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##              master     #2577   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
- Complexity      1756      1770   +14     
===========================================
  Files            180       184    +4     
  Lines           4395      4410   +15     
===========================================
+ Hits            4395      4410   +15     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.