# Add caption option for code blocks #673

Open
opened this Issue Nov 25, 2012 · 18 comments

Projects
None yet

### miekg commented Nov 25, 2012

 It would be nice to have some way to specify a caption for code blocks in the style of the table caption. codeline1 codeline2 codeline3 Code: caption explaning the code above

### miekg commented Nov 25, 2012

 Looking at what (for instance) docbook expects, a better way is to have a figure wrap a code block, i.e. like the following non-working code: ![This is the caption]( A verbatim code block jkasjksajassjasjsajsajkas  )
Contributor

### nougad commented Aug 22, 2013

 If you using fenced code blocks it is possible to add attributes to the code block: ~~~{#test .haskell caption="asdf fdsa"} asdf ~~~  If you compile to latex this gets correct shown in the output (at least if you compile with --listings flag). \begin{lstlisting}[language=Haskell, caption=asdf asf] asdf \end{lstlisting}  If you compile to html the caption="asdf fdsa" is added as an attribute to the 
block but this isn't visible in the document. 
asdf
 But this is more like a hack and not a solution.
Owner

### jgm commented Aug 26, 2013

 You could add a little javascript to make these captions appear in HTML; perhaps it can also be done with pure CSS?
Contributor

### nougad commented Aug 26, 2013

 Good catch! Yes you can even do it with css: pre:after { content: attr(caption); font-weight:bold; }
asdf
 But another thing: caption attribute is no valid html. What do you think of prefixing all attributes with data- to use html5 data attributes? Maybe with a whitelist of valid attributes?

### miekg commented Dec 14, 2013

 Sorry to revisit this. My main "complaint" isn't so much that it is impossible to use a caption, but that the caption technique differs so much from the one in use for tables.

### jamtur01 commented Jul 17, 2014

 I have the same issue - the use of caption causes epub verification to fail.
Owner

### jgm commented Jul 17, 2014

 EPUB contents must be valid xhtml. Try using "data-caption" instead of "caption." (At least, this should work in EPUB3, I don't know about EPUB2.) +++ James Turnbull [Jul 17 14 08:04 ]: I have the same issue - the use of caption causes epub verification to fail. — Reply to this email directly or [1]view it on GitHub. References

### jamtur01 commented Jul 17, 2014

 If I specify data-caption inside a fenced code block I get: 00-frontsmatter.tex:297: Package xkeyval Error: data-caption' undefined in familieslst'. 00-frontsmatter.tex:297: leading text: ...ge=bash , data-caption=Sample code block] When I try to build to PDF. I am trying to build to PDF and ePub for the project. I guess I can sed it before I build the ePub.

### dubiousjim commented Jul 21, 2014

 I like the proposal for the markup syntax. For the rendering, I think (i) either the HTML writer should special-case check for this attribute, and and convert it to data-caption. Maybe the EPUB and other writers too. Or (ii) more complexly, all those writers should check a whitelist and prefix all non-recognized attributes with data-, as @nougad suggested. Or, least preferred, (iii) it should be stored internally as data-caption (though perhaps the reader will accept caption= and silently convert it for you), and it'd be the LaTeX writer that does the special checking and converts it from data-caption (back) to caption.
Contributor

### nichtich commented Sep 11, 2014

 Images and Tables can have captions as well and captions can contain markup (in contrast to the suggested solution with attributes). I'd prefer the common syntax of tables captions:  echo "Hello World"! : Example of a *Hello World* program  My current workaround is to filter code blocks followed by paragraphs that start with : and convert to a 1x1 table (with caption) that contains the code block:  Example of a Hello World program
echo "Hello World"!
 As far as I tried is it not possible to create such 1x1 multiline table with inner code block in Markdown syntax.

Closed

Contributor

### lierdakil commented May 12, 2015

 Can we agree that extending table caption syntax to code blocks is probably best idea so far? For LaTeX output, we can probably leverage float package by defining new float environment for code blocks with captions (if not using listings). For HTML-based output, adding a caption is not an issue. For other formats, it would differ greatly, but in theory doable. Thoughts?
Contributor

### rgaiacs commented May 13, 2015

 From the HTML specification: The figure element represents some flow content, optionally with a caption, that is self-contained (like a complete sentence) and is typically referenced as a single unit from the main flow of the document. The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc. Can we have \$ pandoc -t html5 <
print("Hello.")


### Moonbase59 commented Aug 7, 2015

 I think it should be as universal as possible—I just encountered the problem needing to caption a mathematical formula (display math, as in $$…$$). Would be great if this worked the same style as for tables, images, code …

### Moonbase59 commented Aug 7, 2015

 @lierdakil: Using float seems like a good idea, this could easily work for the others, too! (Like for my formula)
Contributor

### rgaiacs commented Aug 8, 2015

 I just encountered the problem needing to caption a mathematical formula (display math, as in $$…$$). Did you try LaTeX \tag{} command? Caption for mathematical formulas works in a very different way that caption for figures, tables and codes. For example:  +--------------------+ | Equation goes here | (Caption goes here) +--------------------+  instead of  +------------------+ | Figure goes here | +------------------+ Caption goes here  and  Caption goes here +-----------------+ | Table goes here | +-----------------+  Moreover, figures, tables and codes have a strong standard to complain but math does not, i.e. some people are using MathML when others are using MathJax and there still the case of people using images for mathematical formulas.

Open

Open

Closed

Collaborator

### mb21 commented Jun 22, 2018

 @aparcar You can use something like the syntax proposed by @rgaiacs, then write a pandoc filter...
Contributor

### lierdakil commented Jun 22, 2018

 Or, you know, there's support for listings in pandoc-crossref. Which may or may not suit your particular use-case.

Open