Escaping Org Examples in Org

From Karl Voit we have this really useful piece of advice:

TIL: you can use "org" blocks to write #orgmode examples and org-edit-special resulting in correct escaping: https://t.co/oeIR1sccfZ

— Karl Voit (@n0v0id) August 30, 2016

If you follow the link to Stack Overflow you’ll discover the proper way to include Org markup as an example in an Org file. For a trivial example of this see yesterday’s post in which I included a small bit of Org markup.

The idea is that you put the example in an Org source block rather than, say, an Example block:

#+BEGIN_SRC org
* A heading
** Subhead
   With a bunch of other stuff
#+END_SRC

but that’s not quite enough. In my Org source file for this post the above was entered as:

#+BEGIN_SRC org
  ,#+BEGIN_SRC org
  ,* A heading
  ,** Subhead
     With a bunch of other stuff
  ,#+END_SRC
#+END_SRC

As you can see, the Org markup that you want to appear as the example (and not be acted on) is escaped by a comma. Although the Stack Overflow post does not make it clear, the easy way to do this is to insert the #+BEGIN_SRC org and #+END_SRC markers and then call org-edit-special, which is normally bound to 【Ctrl+c '】, and enter your Org example without worrying about escaping. When you finish by typing 【Ctrl+c '】 again, Org mode will automatically add the escaping for you.

I’m really glad to learn this trick. Trying to add Org mode markup in an example never worked well for me. Yesterday, I saw Voit’s tweet and, serendipitously, was able to use it immediately in my next post.