I wonder if org-mode has a feature like asciidoc callouts, and if so what is the syntax?

Below is a explanation on what the callouts are and how it all looks when rendered

AsciiDoc callout example


1 Answer 1


Org Mode does support callouts. The documentation for it is hidden in the Literate Examples section of the manual, but does in fact apply to source code blocks.

Unlike AsciiDoc, Org Mode with Org Babel keeps the code and the documentation cleanly separated.

The example below uses Org Babel to generate a Ruby code file using the :tangle keyword. The Org export functions will generate HTML, much as AsciiDoc does.

Use the (ref:name) syntax to make callouts. The documentation can appear anywhere outside the code blocks. You can create the links easily using C-c C-l or M-x org-insert-link

The -r option in the code block strips the (ref:name) comments from the tangled source code.

The -n option adds line numbers when exporting.

* My example
   #+begin_src ruby -r -n :tangle mysample.rb
     puts 'Hi!'          # (ref:puts)
     print 'ram:'        # (ref:print)
     name = gets.chomp   # (ref:gets)
     puts "Hi! #{name}"  # (ref:deref)

   Code explanation:
   + [[(puts)]] puts the string to stdout
   + Remember the [[(print)][print]] function does not output a newline
   + In line #3, [[(gets)][gets]] reads from =stdin=
   + Finally, [[(deref)][#{name}]] replaces the variable =name= with its value

When you export the above Org Mode file to HTML and open it in a browser using the export dispatcher (`C-c C-e h o) you can hover over the links to highlight the relevant code line.

screenshot of exported HTML with hover

  • 1
    Just when I think org-mode and org-babel cannot get more awesome they surprise me again.
    – elviejo79
    Dec 19, 2020 at 1:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.