What version of Expressive Code are you using?

0.41.6

What is your idea?

I'd like to be able to provide shiki transformers to the Code component, similar to https://docs.astro.build/en/guides/syntax-highlighting/#transformers. I understand there are limitations to what kinds of transformers are supported, this would not require extending that functionality.

Why is this feature necessary?

Background

I am trying to insert links in code snippets to an API reference section for each symbol in the snippet. If I use an item in the code snippet, I want to automatically generate a link in the code block to a page describing the API of that item.

// here's how you do a thing with my library!
import { helpfulFunction } from 'my-lib';

// I want `helpfulFunction` to be a link to /reference/helpfulFunction
helpfulFunction();

For example, Angular does this in their angular.dev documentation with a shiki plugin that wraps identifiers with an anchor tag: https://github.com/angular/angular/blob/main/adev/shared-docs/pipeline/shared/shiki.mts#L87. This transform does not need to modify the code in any way, so it is supported by expressive-code today.

The trouble is, the transformer needs to have a symbol table to know where an identifier comes from. I generate this symbol table in an astro content collection, so it is not available in the expressive code configuration. It is generated by analyzing code with the typescript compiler. In order to use it in the astro template, I would need to define the transformer in the template.

---
import { getEntry } from 'astro:content';
import { Code } from '@astrojs/starlight/components';

import { codeLinksTransformer } from '../utils/code-links';
import someExampleCode from '../examples/some-example.ts?raw';

const symbolTable = await getEntry('apiReference', 'symbols');
---

<Code code={someExampleCode} lang="ts" transformers={[codeLinksTransformer(symbolTable)]} />

Expressive-code-links

I know that there is an existing community plugin, expressive-code-links that can insert links. However, this requires modifying the code in a way where it can no longer be parsed by prettier, which makes it awkward to use. In some cases, the code snippets are themselves automatically generated, then formatted.

I would have to first format the snippet with prettier, then re-parse the snippet to find identifiers to insert the link markup. If I could instead use a shiki transformer, shiki does the parsing for me, and can correctly distinguish identifiers from string literals, for example (as opposed to trying to do this with regex, for example).

Meta strings

Shiki transformers do have access to the meta string for the code block. However, this requires a JSON-stringify round-trip, and only supports data that can be serialized to a string.

A meta string might also be used to define metadata for multiple different transformers, and they would all have to handle each other's formats, ignoring formats they don't expect. This can create incompatibility across transformers/plugins.

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.