Improve code sample tooling

[delucis]

It might be helpful to have some more tools for rendering our code samples.

1. [x] Be able to associate a filename with a code sample in a consistent way.

   In various places we use // some-file.js or preface the code block with a bolded file path. These don’t always work well everywhere so a way to do this that is the same across file formats would be helpful.

2. [x] Be able to highlight specific lines in a code sample.

   This can be helpful to distinguish the key lines in longer samples. Line numbers might be an alternative here although that introduces the possibility for prose to get out of sync with line numbers if the code is changed.

   See also: codehike (from @sarah11918)

3. [ ] Be able to easily copy/paste code samples.

   It’s fairly common for people to want to copy/paste a code sample, so we might want to make this as easy as possible.

4. [ ] Maybe a way to collapse some code by default? This would allow longer more complete code samples where the full context is available but only pertinent lines are immediately shown.

5. [ ] (h/t @hippotastic) Where it makes sense, could we connect code samples to “Try it out now” links that point to Stackblitz? (Or offer inline interactivity with https://github.com/withastro/astro-playground!)

6. [x] The beta React docs site has a cool little component for terminal sippets. We could do something similar with a remark plugin that targets code blocks tagged sh/shell?

If possible it would be good to support this with minimal syntax changes. Perhaps with a remark plugin that can read extra metadata after the triple backtick?

```js src/pages/endpoint.js
export function get() {
}
```

[sarah11918]

Love these ideas @delucis !

Re: 3. Here's something I keep wishing I had a good solution for: indicating (visually) that a certain line of code belongs within the code fences, but allowing the user to easily copy/paste just the line itself, and not the fences. (Presumably, they already have those, and other things, in their Astro component.) Typically we show the code fences in a code snippet, but one-click copy buttons would normally copy the entire contents.

In some cases, it's as almost if I'd like the code fences to be part of the code sample's styling instead of content, maybe?

[hippotastic]

As discussed on Discord, I'd love to work with you on that! 😄 I can tackle the subtask of creating a remark plugin for code blocks that:

• supports all the typical syntax we're using in docs right now to indicate which file name a code snippet should have
• also allows adding the file name after the language indicator in the opening code fence line
• allows specifying line numbers to focus on or even highlight in the same place (metadata at the end of the opening code fence line)
• finally wraps the processed code blocks inside a special "code snippet" component, passes the extracted information as props to it, and the code as contents

We (you? 😄) can then do whatever we like with the code by using the new code snippet component:

• In a first step, we could limit ourselves to better styling only:
  • making the component display a file name tab when a file name was detected
  • making it look like a terminal when the language matches a shell language
  • applying the necessary CSS styles to highlight lines and line ranges (if given)
• In a second step, we could make it interactive:
  • add a little "copy to clipboard" icon in the top right corner
  • hide non-focused/highlighted lines by default in longer snippets and allow readers to expand the whole snippet on demand
  • and maybe in the future allow running the code example in a sandbox

What do you think?

[delucis]

That sounds perfect! I give full permission to Hippo the hell out of this 🚀

And as we discussed briefly — I’m happy to step in with styling help when the time comes.

[kylebutts]

Torchlight has a syntax I find quite intuitive where you insert comments (in the language you're writing in so // for javascript). Then, you can look for a comment flag !astro among the comments when shiki parses the code.

A couple examples of cool things you can do:

• Focus a set of lines
• Collapsible chunks
• Add html classes/ids to lines/tokens

A while ago I wrote some (poorly written) code that worked with shiki parsing to do this: https://github.com/kylebutts/shiki-vue/blob/main/src/components/comment_commands.js

[hippotastic]

Hey Kyle, thank you for the input to this!

A lot has happened since my last comment on this issue and we already have line & expression highlighting with multiple marker styles (marked, inserted, deleted) now.

The syntax is currently located only in the meta information after the opening code fence.

I'm planning to move the code snippet functionality with all marking features, file name tabs and customizable styles into an Astro integration NPM package. I'm happy to accept input and PRs there then. :)

I'll let you know when the migration has happened!

[sarah11918]

@hippotastic @delucis Do we want to consider breaking this out into the remaining tasks, rather than have this hanging over our head when SO MUCH has already been completed? I think we did this sort of thing with some i18n tasks?

[delucis]

Can do! We might want to wait until Hippo's magic code sample package arrives. That way we can see what is still outstanding and what will be tackled there.

[sarah11918]

Feels like maybe a good time to break this up into tasks? @hippotastic @delucis ?

Seems like: ✅ 1. making code samples copy/pastable seems like a more straightforward, and immediate task (especially since that will help us with the tutorial!) WANT! SOON(ish)!

❌ 2. Link to Stackblitz I think becomes less desirable since we expect to have some embeddable, interactive components eventually thanks to Nate? Can we agree that that is preferable to sending people to an external StackBlitz (and maybe crashing some poor Chromebook??) for a small code sample? Abandon ship?

❌ 3. Sarah's pipe dream of collapsable code lines can be put on hold? Live on in this closed issue? I also think if/when we have embedable code playgrounds, maybe THAT interface can also collapse some code. So, it's less of a code example tool and more of an "can we bring the normal editor feature of being able to collapse some lines into our interactive playground." Propose we sink this ship?

[hippotastic]

Hello again! :)

1. As we discussed, I'm already working on the code snippet package right now. :) The copy & paste function will be a part of it, so that's something we don't even need to track here anymore IMO because it lives in a separate repository anyway.

2. I agree that it's unclear if we really need/want to send people off to StackBlitz etc. - keeping people in the docs would be preferable in my opinion. That's why this item was also mentioning "inline interactivity". It depends on the availability of a fully-working Astro playground though, so maybe we can also close this part until we receive news that it's ready.

3. To be honest, this idea was something that never really clicked for me anyway as I didn't see a lot of examples where it would be useful. We can close this IMO.

I'm not sure if your intention of checking on this issue was to get rid of old issues, but if it was, I think we can close this at any time as none of the points really make sense to be tracked as an issue here.

[sarah11918]

Taking Hippo's advice and closing these as non-trackable here!

[kylebutts]

@sarah11918 @hippotastic. I do think there's value in having this. In a lot of places in the docs, code gets "implied" by // ... comments. It would be nice to have the full code in there to let people easily try have a working example (when copy and pasting), but would allow the part of the code that isn't necessary for the point trying to be made to be hidden.

Collapsible code is relatively easy to do using html (see torchlight) and the collapsible marker can be accessed and styled via css using the open attribute which is quite nice as well.

First line

Other lines of code can be hidden

<details>
<summary>First line</summary>
Other lines of code
can be hidden
</details>

[hippotastic]

Hey @kylebutts, thanks for chiming in on this again! I completely understand how this would work technically, my issue with this idea was from a docs content perspective:

I did a quick walk through our existing docs, trying to find code samples where the "implied" left out code would actually be the reason why a copied & pasted version would not work. From what I've come across, we usually use such implied content to show possible points to extend the code, but it would still work fine without adding any code there.

If you have found multiple examples in docs where this is not the case, please feel free to share them and we can rethink our position! :)