12

In every renderer I've tried, code and code-block seem to have the exact same result: a block of code. Both generate the exact same html -- including classes and tag kind (using I think it was docutils?):

<pre class="code [language] literal-block">

So, what's the difference? Why do we have both? Are there any renderers that render them differently? Is there a semantic difference?

P.G.
  • 623
  • 6
  • 13
potato
  • 357
  • 1
  • 14

1 Answers1

18

code is a reStructuredText directive. code-block is a Sphinx directive.

The code-block has a different set of options to the codedirective. E.g. :emphasize-lines:

As you are using Sphinx I would recommend using the code-block directive.

When using code-block I always get the correct highlighting. When using code I sometimes get colors and sometimes just literal code blocks. I have yet to figure out what combinations of setting in conf.py that predictably generates colored output.

The code directive does have the advantage that the document can be used both in a Sphinx document tree and at the same time as a stand-alone reStructuredText document.

P.G.
  • 623
  • 6
  • 13