Annotated Code Blocks

Code annotations are visual markers inside a code block that can be used to highlight a line of code and referenced outside of the code block for further discussion. A simplistic way of implementing a code annotation would be something like:

<?xml version='1.0' encoding='UTF-8'?>
<runtimeConfig>
  ...
(1) <configTag attr1='1' attr2='58'>value</configTag>
(2) <otherConfigTag attr1='hello' attr2='goodbye'>another value</otherConfigTag>
  ...
</runtimeConfig>

• (1) Explanation of configTag…
• (2) Explanation of otherConfigTag…

which in markdown is simply:

~~~xml
<?xml version='1.0' encoding='UTF-8'?>
<runtimeConfig>
  ...
(1) <configTag attr1='1' attr2='58'>value</configTag>
(2) <otherConfigTag attr1='hello' attr2='goodbye'>another value</otherConfigTag>
  ...
</runtimeConfig>
~~~

* (1) Explanation of `configTag`...
* (2) Explanation of `otherConfigTag`...

While this technically “works”, it’s not very friendly for documentation, as before using the code inside the block, a user must manually:

• remove annotations (e.g. (1), (2))
• fix indentation

Better would be something like this:

<runtimeConfig>
  ...
  <configTag attr1='1' attr2='58'>value</configTag>
  <otherConfigTag attr1='hello' attr2='goodbye'>another value</otherConfigTag>
  ...
</runtimeConfig>

• Explanation of configTag…
• Explanation of otherConfigTag…

which is copy-pastable and retains proper indentation. This is archived though the highlight_with_annotations block:

{% highlight_with_annotations xml %}
<runtimeConfig>
  ...
  <configTag attr1='1' attr2='58'>value</configTag>{% raw %}{% annotation 1 %}{% endraw %}
  <otherConfigTag attr1='hello' attr2='goodbye'>another value</otherConfigTag>{% raw %}{% annotation 2 %}{% endraw %}
  ...
</runtimeConfig>

{% endhighlight_with_annotations %}

* {% annotation 1 %} Explanation of `configTag`...
* {% annotation 2 %} Explanation of `otherConfigTag`...