v1.3.0: “Patches in Production”

A problem (about dead maintainers)

This post talks about changes I’ve made to astro-erudite in v1.3.0!

I recently found myself caught between two syntax highlighting packages that I absolutely needed for astro-erudite. On one hand, the current template uses rehype-pretty-code as its main syntax highlighting solution, but due to issues with its inherent implementation and missing features that I needed, I had created a bunch of custom transformers to make it do what I wanted, and the whole setup was getting unwieldy. I then discovered Expressive Code, which had everything I wanted out of the box—collapsible code sections, terminal and editor frames, gutter comments—it was perfect! Well, almost perfect.

The primary issue was that Expressive Code doesn’t support inline syntax highlighting, which is non-negotiable for me since I need my inline code snippets to look as good as my code blocks (so I could do stuff like console.log("Hello, world!".split('').reverse().join(''))). So I opened a feature request at expressive-code/expressive-code#250 and the maintainer seemed interested, saying they’d get around to it eventually. Implementing this feature is a lot easier said than done though, and I summarized it well in another thread:

@jktrn: […] expressive-code is already interested in implementing inline code support, but it would be a bit nuanced to add since it has to:

• allow existing plugins to continue working normally with block-level code (without breaking changes),
• enable new plugins to explicitly declare support for inline code,
• and provide ways for plugins to distinguish between inline and block-level code processing.

However, I needed a solution immediately. My first thought was to use both packages together—Expressive Code for block code and rehype-pretty-code for inline code. However, importing both at the same time caused everything to break spectacularly.

The hunt for a solution

Digging into the rehype-pretty-code docs, I noticed they had a bypassInlineCode option that lets you skip inline code highlighting (it was actually added in a really recent update). But what I needed was the opposite, which would be a way to make it only handle inline code and bypass blocks entirely.

So I opened a feature request at rehype-pretty/rehype-pretty-code#247 for a theoretical bypassBlockCode option. I got no response, since the repository seemed unmaintained for a bit since it seems like the maintainer has moved onto other projects.

Fast forward a few months, and user @kelvindecosta comments on my issue:

[@kelvindecosta]: Hey @jktrn, did you figure out a workaround for this? I’m interested in setting this up alongside expressive-code.

After I replied that I hadn’t figured out a workaround yet, they sent me a brilliantly hacky solution a couple days later:

[@kelvindecosta]: Hey again @jktrn, I have found an unconventional way to achieve this.

If you’re using pnpm or bun, you can use their patch functionality to customize the contents of the node_modules/rehype-pretty-code package.

I only recently learned about this feature, and it is a good workaround for the time being. Here are the steps:

1. Run pnpm patch rehype-pretty-code. This will instruct you to edit the files in a certain directory.
2. Patch out the isBlockCode function to always return false. This will instruct the plugin to not process any block code elements.
3. Run pnpm patch-commit <path/to/files>. This will create a nice patches folder with the right changes.

Performing surgery on node_modules

This happened to be exactly what I needed! I went into my node_modules directory and made the changes manually:

18
function isInlineCode(element, parent, bypass = false) {
19
  if (bypass) {
20
    return false;
21
  }
22
  return element.tagName === "code" && isElement(parent) && parent.tagName !== "pre" || element.tagName === "inlineCode";
23
}
24
function isBlockCode(element) {
25
  return element.tagName === "pre" && Array.isArray(element.children) && element.children.length === 1 && isElement(element.children[0]) && element.children[0].tagName === "code";
26
  return false;
27
}

From here, I ran npx patch-package rehype-pretty-code, which created a patches/rehype-pretty-code+0.14.1.patch file with the changes I made:

1
--- a/node_modules/rehype-pretty-code/dist/index.js
2
+++ b/node_modules/rehype-pretty-code/dist/index.js
3
@@ -22,7 +22,7 @@ function isInlineCode(element, parent, bypass = false) {
4
   return element.tagName === "code" && isElement(parent) && parent.tagName !== "pre" || element.tagName === "inlineCode";
5
 }
6
 function isBlockCode(element) {
7
-  return element.tagName === "pre" && Array.isArray(element.children) && element.children.length === 1 && isElement(element.children[0]) && element.children[0].tagName === "code";
8
+  return false;
9
 }
10
 function getInlineCodeLang(meta, defaultFallbackLang) {
11
   const placeholder = "\0";

This simple modification forces rehype-pretty-code to completely ignore block code elements by always returning false from the isBlockCode function. Now Expressive Code handles all block code formatting, while rehype-pretty-code still beautifully handles my inline code. And just like that, they’re working in perfect harmony!

Please don’t perform surgery on your node_modules

Absolutely do not do this for production sites (your personal blog does not count =￣ω￣=). Directly patching node modules is generally discouraged because patches can break with updates and create maintenance headaches down the road.

But sometimes, when you’re working at the bleeding edge of web development, temporary solutions like this become necessary. The better approach would be to just wait for Expressive Code to implement inline syntax highlighting. But, since it’ll take a while for reasons aforementioned, I’ll stick with my janky solution. This patch buys me time until either rehype-pretty-code gets maintained again and implements the feature properly, or Expressive Code adds inline code support.

In the meantime, astro-erudite now has both beautiful code blocks and inline syntax highlighting. And now it’s available for all of you to use!