The workshop currently renders fenced code through a small hand-rolled Shiki wrapper (components/blog/code-block.tsx -> highlightToHtml in lib/demos.ts), with a rehype plugin carrying fence meta so ```ts {6-7} can emphasise lines.
The previous iteration of this site used rehype-expressive-code, which was dropped in the rebuild. Worth reconsidering for the workshop specifically.
Note rehype-expressive-code is a rehype plugin and slots into the MDX pipeline. The <Code> component documented at https://expressive-code.com/key-features/code-component/ is Astro-only and is not the relevant part. Expressive Code also has no tabbed/multi-language switching — its "frames" render a filename header that looks tab-like but is one file. Multi-language switching is tracked separately in #6.
What it would buy, against the actual content
| Feature |
Why it matters here |
ins/del diff markers |
The 20 blocks converted from Hugo hl_lines are all "add these lines" steps. They currently render as a flat highlight that shows where but not what changed |
| Collapsible sections |
1000-assertion-test.mdx shows the same evolving file five times; collapsing unchanged regions turns long repeats into readable deltas |
| Terminal frames |
Many $ cdktn ... blocks are visually identical to source listings |
| Copy button |
138 fenced blocks the reader is meant to run |
| File titles |
The prose repeatedly says "edit hitcounter.ts" and then shows an unlabelled block |
Cost
- Replaces the Shiki path shared with the homepage guided tour (
lib/demos.ts), so both need to stay visually consistent.
- Brings its own theming to reconcile with the dual-theme
--shiki-light / --shiki-dark CSS variables in app/globals.css.
- The Hugo-to-MDX conversion script maps
hl_lines to {a,b-c} meta; adopting diff markers means revisiting that mapping.
Cheap first slice, independent of the decision
CodeBlock already accepts a filename prop, but the pre override in components/blog/mdx-components.tsx only parses {1,3-5} from fence meta. Extending that parser to also read title="hitcounter.ts" would give filename headers across the whole workshop with no new dependency, and is useful whether or not Expressive Code is adopted.
The workshop currently renders fenced code through a small hand-rolled Shiki wrapper (
components/blog/code-block.tsx->highlightToHtmlinlib/demos.ts), with a rehype plugin carrying fence meta so```ts {6-7}can emphasise lines.The previous iteration of this site used
rehype-expressive-code, which was dropped in the rebuild. Worth reconsidering for the workshop specifically.Note
rehype-expressive-codeis a rehype plugin and slots into the MDX pipeline. The<Code>component documented at https://expressive-code.com/key-features/code-component/ is Astro-only and is not the relevant part. Expressive Code also has no tabbed/multi-language switching — its "frames" render a filename header that looks tab-like but is one file. Multi-language switching is tracked separately in #6.What it would buy, against the actual content
ins/deldiff markershl_linesare all "add these lines" steps. They currently render as a flat highlight that shows where but not what changed1000-assertion-test.mdxshows the same evolving file five times; collapsing unchanged regions turns long repeats into readable deltas$ cdktn ...blocks are visually identical to source listingshitcounter.ts" and then shows an unlabelled blockCost
lib/demos.ts), so both need to stay visually consistent.--shiki-light/--shiki-darkCSS variables inapp/globals.css.hl_linesto{a,b-c}meta; adopting diff markers means revisiting that mapping.Cheap first slice, independent of the decision
CodeBlockalready accepts afilenameprop, but thepreoverride incomponents/blog/mdx-components.tsxonly parses{1,3-5}from fence meta. Extending that parser to also readtitle="hitcounter.ts"would give filename headers across the whole workshop with no new dependency, and is useful whether or not Expressive Code is adopted.