Code callouts support

[viglucci]

Asciidoctor supports the concept of "code callouts", which I blieve would be a great addition to remark.

For example, with Asciidoctor, the following syntax:

[source,ruby]
----
require 'sinatra' // <1>

get '/hi' do // <2>
  "Hello World!" // <3>
end
----
<1> Library import
<2> URL mapping
<3> HTTP response body

Would produce the following output:

I believe that it would be sufficient enough for Remarkjs to be able to parse the comments inside of the code block // <1> (etc.) and produce the tag portion within the block.

The tag descriptions output under the code block could likely be manually created by the caller in their MD or MDX file.

As a contrived example when used with MDX, this could be consumed as so:

[ChristianMurphy]

A plugin contributing a custom parser for callouts could be an option.
Though using standard and semi-standard markdown features like code block and directive would likely be easier and more ideomatic.
That could look something like:

```ruby
require 'sinatra'

get '/hi' do
  "Hello World!"
end
```

:callout[Library import]{line=1}
:callout[URL mapping]{line=3}
:callout[HTTP response body]{line=4}

https://astexplorer.net/#/gist/9634fb2c53a38f220e0e5d42163ea68f/7481b8f202f84b8765da24a7eb5b4ccbe4c8105b

[viglucci]

Interesting. I think I agree that keeping within the features of markdown would be the better route.

For some additional context on my use-case, I am specifically attempting to accomplish this functionality within the context of a Docusaurus website. Digging through their existing implementations I see that the project provides its own support/implementation for accomplishing line highlighting, so now I'm second guessing if remark is the layer at which support for this functionality would be added. If indeed that inclination is correct then I believe this would be more suited as either a feauture of prism-react-renderer or as a prism plugin, but granted I'm not educated enough at this time to know for sure.

[wooorm]

docusaurus is also built on remark and rehype, but seems they’re highlighting on the frontend perhaps?

Anyway, yes, this is not something for the core of remark: it can go in a plugin (and if so, specifically a rehype plugin as it’s better suited for a HTML syntax tree)!

[ChristianMurphy]

Thanks for starting the discussion @viglucci !
We're in the process unifying ideas in with discussions unifiedjs/collective#44
If you'd like to continue this thread, or start a new one https://github.com/remarkjs/remark/discussions/categories/ideas will be the home for ideas going forward.