Titling code blocks

[aubertc]

Per @etremel :

I notice that the user guide for our website/resources says that each code snippet needs a title: in section “Source code” it says “Title each source code block included in markdown, this will create a URL for the code block and enables linking to it.” However, I can’t figure out how to add a title to a code block in Markdown. The official Pandoc-Markdown documentation doesn’t say that code blocks can have titles; it only says that tables can have titles, if you put a line of text beginning with “Table:” after the table.

Is there something I’m missing here, or is the ability to give code blocks titles/captions something that hasn’t been implemented yet? I’d like to format my code blocks properly as I write the lecture notes, but so far I haven’t written any titles for them.

[aubertc]

This is a known issue / limitation.
It has been discussed quite a lot and there are "hacky" ways using the listing package (for the pdf) and some ccs styling.

However, it seems that this is a feature that is currently under active development, so I suggest we wait on pandoc to catch up. (Also, the listing package is in my opinion not as nice as what we have now).

My experience is that pandoc's release cycle is quite fast, and that they do solve issues when they set their mind to it.

[nkrusch]

I have written this comment about titling code blocks in user guide preemptively, with the intent that it will be done eventually. The part about "how to do it" is an outstanding item in the platform plan. I agree with Clément, we should wait for support from pandoc.