Feature: Bullet Annotations!
bdenham opened this issue · comments
Provide a bullet annotation option. Nothing fancy, so as not to complicate the implementation.
Use Case:
Bullet annotations provide convenient ways to reference specific code blocks in the documentation. With bullet annotations in the code, you can match them in the docs using numbered or lettered lists to make explanations easier to read.
Suggestions (see example):
- Position: Top-left, for code blocks only; not for text annotations.
- Shape: Square, so that they appear to "extend" from the code block's left border.
- Color: Match the left border color of code block.
- Content: Single alphanumeric character: 1, 2, 3... A, B, C..., etc.
Thanks!
That's a great idea! Thank you for even including a mockup!
This should indeed be simpler to implement on the HTML/CSS side than the line numbers (feature idea from another issue) which are unfortunately way more complex. The only potential downside I can see is that the single character would replace the +/- of lines marked as inserted or deleted, as also visible in your mockup. Do you think this is a problem, and do you see any potential solutions?
I'm just thinking about how the syntax could look. We currently have [ins/del/mark=]{n[-n][,...]}, and I think we should try adding the character/number label in the comma-separated parts inside the curly braces somewhere, so you can assign a character to each line or line range. Do you have any preferences/ideas on that?
The only potential downside I can see is that the single character would replace the
+/-of lines marked as inserted or deleted, as also visible in your mockup. Do you think this is a problem, and do you see any potential solutions?
Yes, I was thinking about that when doing the mockup, and I don't think it will be an issue. Here's my reasoning: If you use a bullet annotation along with ins and del markers (even for single lines), then you probably intend to reference that bullet in the docs, where you would add a description for each bullet. Otherwise, you wouldn't use bullet annotations.
I'm just thinking about how the syntax could look. We currently have
[ins/del/mark=]{n[-n][,...]}, and I think we should try adding the character/number label in the comma-separated parts inside the curly braces somewhere, so you can assign a character to each line or line range. Do you have any preferences/ideas on that?
Yeah, I like that! Maybe the bullet character could be in quotes at the beginning or end of the comma separated list, where it would be used to annotate the line numbers and line ranges that follow or precede. Example usages:
Add to single line numbers:
```jsx title="example.js" ins={'1', 3} del={'2', 4} mark={'3', 11}Add to a single range of line numbers:
```jsx ins={'1', 3-4} del={'2', 5-6} mark={'3', 8-9}And just to push the usage examples to their logical conclusion, but definitely not necessary if implementation is difficult.
Add to multiple line numbers and ranges:
```jsx ins={'1', 3, 10, 20} del={'2', 5-6, 12-18}This would result in bullet 1 appearing on lines 3, 10, 20; and bullet 2 appearing for line ranges 5-6 and 12-18.
This is simply a short cut for using three different ins annotations and two different del annotations.
Hey @hippotastic! Happy New Year!
Have you given any more thought to this? Let me know if I can help.
Happy New Year to you, too! 🥳
I have not come to any feature requests yet as I'm still finishing the documentation website for EC. I made significant progress there in the past few weeks and am expecting to launch it in the first week of 2024!
After that, I can focus on feature requests again and will have a look at yours as well!
Sorry that this is taking a while already, I'm just a one-man show and I'm doing this in my spare time. :)
I finally got to implementing this. 🥳
I opted for a slightly different syntax using a colon : to separate the quoted labels from the line ranges, as I felt that this conveys being a label for the following ranges better than a plain comma.
Feel free to have a look at the PR and its deploy preview and let me know if you have any feedback before I publish this!
Excellent! I’ll run it through its paces tomorrow.
I just committed a small change that also allows your shortcut syntax to add multiple labels to non-consecutive line ranges (e.g. {"A":3-5,10-12,17}). I also gathered feedback from the Astro DX team regarding the syntax and they liked it.
I think we're ready to go! Unless you have anything that really needs to be changed, I'd release this as is. :)
Yes, go for it! Looks great! Extremely well done. And the additional feature for adding the same label to multiple line ranges is an amazing extension that I for one will use extensively. Bravo, Hippo!
Your great preparation of this feature request made it really easy to implement. Thank you! https://expressive-code.com/releases/#0310