MarkdownSnippets icon indicating copy to clipboard operation
MarkdownSnippets copied to clipboard

Support Some Expressive Code Features

Open khalidabuhakmeh opened this issue 1 year ago • 1 comments

Expressive code features allow developers to add more metadata to a code block to illustrate the intent of the code block better. For example, you can highlight several lines, highlight symbols via regular expressions, mark text as inserted or deleted, and even perform a diff.

Describe the solution

Allow developers to add additional metadata next to the snippet name that will get added to the code block at render time.

// begin-snippet: App:HelloWorld
// Program.cs
Console.WriteLine("Hello, Again!");
Console.WriteLine("Hello, Again!");
Console.WriteLine("Hello, Again!");
// end-snippet

would become in your C# code

// begin-snippet: App:HelloWorld | {2-2} "Hello" title="Hello 3x"
// Program.cs
Console.WriteLine("Hello, Again!");
Console.WriteLine("Hello, Again!");
Console.WriteLine("Hello, Again!");
// end-snippet

And in markdown would become

<!-- snippet: App:HelloWorld -->
<a id='snippet-App:HelloWorld'></a>
```cs {2-2} "Hello" title="Hello 3x"
// Program.cs
Console.WriteLine("Hello, Again!");
Console.WriteLine("Hello, Again!");
Console.WriteLine("Hello, Again!");
```
<sup><a href='#snippet-App:HelloWorld' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->

The resulting output might look something like

image001767-2024-12-13 -14-36-06

Additional context

See Expressive Code at this link. https://starlight.astro.build/guides/authoring-content/#expressive-code-features and here https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code

khalidabuhakmeh avatar Dec 13 '24 19:12 khalidabuhakmeh

@SimonCropp I was thinking about taking a crack at implementing this with some backward compatibility in mind and I think I've come up with a syntax that should be easy to pull off.

// begin-snippet: HelloWorld({1} title="Getting Started")
Console.WriteLine("Hello World");
// end-snippet

We could pull all the text from within the parenthesis and treat that as something to be added to the final code block.

<!-- snippet: HelloWorld -->
```cs {1} title="Getting Started"
Console.WriteLine("Hello World");
```
<!-- endSnippet -->

What do you think? This would also address the issue in #716.

khalidabuhakmeh avatar Apr 26 '25 20:04 khalidabuhakmeh