UP  |  HOME

Markup Guide

Blocks with appearance similar to tcolorbox

Named and Captioned blocks

  • #+NAME
    • is for naming blocks so they may be referenced elsewhere
    • must be unique, or it can cause blocks to not execute
  • #+CAPTION
    • applies to blocks, images, figures, and tables
    • If you apply it to a source block, but only export results then the caption is only relevant to the source block (which never appears)
    • To caption the results you must:
      • #+NAME: name the source block
      • :wrap the output, can be 'src lang', 'example', etc.
      • Follow the source block with a #+CAPTION line
      • Follow that with #+RESULTS: name

A quick example

  • Named
    #+NAME: named_block
#+BEGIN_SRC elisp
(message "This is example code")
#+END_SRC

    (message "This is example code")
  • Captioned
    #+CAPTION: A captioned block
#+BEGIN_SRC elisp
(message "This is example code")
#+END_SRC
    Listing 1: A captioned block
    (message "This is example code")

Command examples

I use examples for showing commands. 

#+CAPTION: A command example
#+BEGIN_EXAMPLE
commands
#+END_EXAMPLE
A command example
commands

Command output

Command output is just an example with a different environment/class. 

#+CAPTION: A captioned command output
#+ATTR_LATEX: :environment cmdout
#+ATTR_HTML: :class cmdout
#+BEGIN_EXAMPLE
some output
#+END_EXAMPLE
A command output
some output

Notes

Notes don't support captions in HTML export because I'm just filtering special blocks. I could add support, but I need to combine it with the drislox-html-gallery function, since they both need to filter the arguments to org-html-special-block. 

#+CAPTION: A Note
#+BEGIN_note
Extra information

Things you may want to know
#+END_note
A Note

Extra information


Things you may want to know

Source code

#+CAPTION: A src block
#+BEGIN_SRC elisp
(message "This is example code")
#+END_SRC
Listing 2: A src block
(message "This is example code")

Displaying the results of source code

Here we want to apply the caption to the output, not the source block.

TODO org-lint thinks captions applied to results are orphaned. 

#+NAME: results_of_source
#+BEGIN_SRC shell :exports results :results output :wrap example
(princ "This is example code")
#+END_SRC

#+CAPTION: Results of evaluating a source block
#+RESULTS: results_of_source
Results of evaluating a source block
This is example code

You could also :exports both instead of results, then apply separate captions to each one. 

#+NAME: both
#+CAPTION: Source block for example code
#+BEGIN_SRC shell :exports both :results output :wrap example
(princ "This is example code")
#+END_SRC

#+CAPTION: Results block for example code
#+RESULTS: both
Listing 3: Source block for example code
(princ "This is example code")
Results block for example code
This is example code

Displaying the results of source code as source code

#+NAME: source_results_as_source
#+BEGIN_SRC elisp :exports results :results output :wrap src c
(princ "int main(){\n\tprintf(\"Hello, World!\");\n\treturn 0;\n}\n")
#+END_SRC

#+CAPTION: Results of evaluating source code as source code
#+RESULTS: source_results_as_source
Listing 4: Results of evaluating source code as source code
int main(){
        printf("Hello, World!");
        return 0;
}

Including other files

Org's include directive can include other org files, but I mostly use it for other text file formats.

As source

#+CAPTION: hello.c
#+INCLUDE: "programming/exercises/practical_c_programming/hello.c" src c
Listing 5: hello.c
#include <stdio.h>
int main()
{
    printf("Hello World\n");
    return (0);
}

Filtering with sed (or other tools)

Remember, with :wrap src we need a name, then place the caption on the results block afterwards. 

#+NAME: hello_hi
#+BEGIN_SRC shell :exports results :results output :wrap src c
sed -e 's/Hello/Hi/' "programming/exercises/practical_c_programming/hello.c"
#+END_SRC
#+CAPTION: hello.c (Hi)
#+RESULTS: hello_hi
Listing 6: hello.c (Hi)
#include <stdio.h>
int main()
{
    printf("Hi World\n");
    return (0);
}

Using files as inputs to code blocks

These blocks need to be named, and the name must be unique.

This file won't be visible, but will be accessible from the name 

#+NAME: hello
#+INCLUDE: "programming/exercises/practical_c_programming/hello.c" export

For example we pass it to another block: 

#+BEGIN_SRC elisp :exports results :results output :var hello_source=hello
(string-match "\\(Hello [[:word:]]+\\)" hello_source)
(princ (match-string 1))
#+END_SRC

Hello World

We can also import it the same way, but with visibility: 

#+NAME: hello2
#+INCLUDE: "programming/exercises/practical_c_programming/hello.c" example

#include <stdio.h>
int main()
{
    printf("Hello World\n");
    return (0);
}

It can even be passed as standard input: 

#+BEGIN_SRC shell :stdin hello2 :exports results :results output
grep Hello
#+END_SRC

printf("Hello World\n");

Quotes and Verses

Quotes and Verses are part of LaTeX. In HTML, quotes become <blockquote>, and verses become paragraphs with class verse, and break tags for all line breaks. 

#+BEGIN_QUOTE
Things people have said
#+END_QUOTE

Things people have said 

#+BEGIN_VERSE
Beautiful prose
#+END_VERSE

Beautiful prose

Section Headlines

'Section Headlines' is a first level section headline. In HTML, fourth level and deeper headlines become unordered lists.

  • h1 is used for the page title
  • h2 should be top-most headline
  • h3 second level
  • h4 third level

In LaTeX fourth level and deeper become ordered lists.

LaTeX whines about being too deeply nested at the 8th level.

LaTeX also places the contents next to the headline at the fourth level, probably because org exports them as list items. 

** Second level
:PROPERTIES:
:UNNUMBERED: notoc
:END:
second text
*** Third level
:PROPERTIES:
:UNNUMBERED: notoc
:END:
third text (the property above is just to keep it out of my table of contents)
**** Fourth level
fourth text
***** Fifth level
fifth text
****** Sixth level
sixth text
******* Seventh level
seventh text

Second level

second text

Third level

third text (the property above is just to keep it out of my table of contents)

  • Fourth level

    fourth text

    • Fifth level

      fifth text

      • Sixth level

        sixth text

        • Seventh level

          seventh text

Images

Include image

[[images/ai generated/lain builds computers/lain_builds_a_navi_computer_with_sgi_workstations_dhixo8y.jpg]]
lain_builds_a_navi_computer_with_sgi_workstations_dhixo8y.jpg

Image with caption

#+CAPTION: lain builds a navi with sgi workstations
[[images/ai generated/lain builds computers/lain_builds_a_navi_computer_with_sgi_workstations_dhixo96.jpg]]
lain_builds_a_navi_computer_with_sgi_workstations_dhixo96.jpg
Figure 1: lain builds a navi with sgi workstations

Modifying images

These all use imagemagick's convert utility. I have some other things I might want to implement here such as:

  • renaming files (to prevent modification collisions)
  • text overlay
  • blur
  • resize (we already auto-resize to cut file size)

Crop an image

Give dimensions (width by height), and a starting x,y offset. (origin is top left) 

#+CALL: convert(crop="700x810+250+40")
#+ATTR_HTML: :width 600
[[images/ai generated/lain builds computers/lain_builds_a_super_computer_from_sparc__sgi__and__dhixncg.jpg]]
lain_builds_a_super_computer_from_sparc__sgi__and__dhixncg.jpg

Draw a red rectangle

Give coordinates (x,y) for upper left, and lower right corners. (origin is top left) 

#+CALL: convert(rect="600,120 850,350")
#+ATTR_HTML: :width 600
[[images/ai generated/lain builds computers/lain_builds_a_navi_computer_with_sun_sparc_worksta_dhixois.jpg]]
lain_builds_a_navi_computer_with_sun_sparc_worksta_dhixois.jpg

Hide things with a black rectangle

Same specification as the red rectangle above. 

#+CALL: convert(hide="380,600 580,800")
#+ATTR_HTML: :width 600
[[images/ai generated/lain builds computers/serial_experiments_lain_builds_a_super_computer_po_dhiwg10.jpg]]
serial_experiments_lain_builds_a_super_computer_po_dhiwg10.jpg

Generating images

Dot output (graphviz)

#+BEGIN_SRC dot :file ./figures/hello.svg :exports results
digraph G {Hello->World}
#+END_SRC
hello.svg

Shell with convert/montage

A longer example. Include a file, feed it to a shell script, write the output to a file. Display it as an image in the output.

XeTeX hated this PNG file becase it was 16-bit. Specifying 'PNG8' to montage makes a suitable file. 

#+NAME: colors
#+INCLUDE: "my_monokai.txt" example

#E8E8E2 White
#333333 Dark grey
#C4265E Purplish red
#2AD043 Green
#FA9429 Pumpkin
#6A7EC8 French blue
#8C6BC8 Deep lavender
#56ADBC Teal blue
#E3E3DD Light grey
#666666 Charcoal grey
#F92672 Cerise
#63DE5D Slime green
#FFBA68 Apricot
#819AFF Soft blue
#AE81FF Liliac
#66D9EF Robin's egg
#E8E8E2 White
#1B1D1E Almost black

#+NAME: color_palette
#+BEGIN_SRC shell :stdin colors :results file :file generate_palette.png :output-dir ./figures :exports results
while read color desc; do case $color in '') continue ;; esac; convert -label \
"$desc\n$color" -size 70x50 xc:$color +depth miff:-; done | montage - -frame 5 \
-tile 8x -geometry +2+2 -background none PNG8:-
#+END_SRC
generate_palette.png

Tables

Tables are messy because LaTeX tables are complex. I default to tabular environment there, but sometimes I need tabularx or longtable.

Booktabs-like CSS is used to improve table appearance, but none of the below examples are really relevent if you're viewing the HTML export. 

#+ATTR_LATEX: :align lll
|stuff|junk|more |
|-----+----+-----|
|word |two |three|
stuff junk more
word two three 
#+ATTR_LATEX: :environment tabularx :width \textwidth :align llX
|stuff|junk|more                              |
|-----+----+----------------------------------|
|word |two | Long text that needs to wrap because it is long. Much longer than most page widths. You might even consider the long term consequences of having many words in one cell, but you don't have to because tabularx has the X alignment.|
stuff junk more
word two Long text that needs to wrap because it is long. Much longer than most page widths. You might even consider the long term consequences of having many words in one cell, but you don't have to because tabularx has the X alignment. 
#+ATTR_LATEX: :environment longtable :align lll
|stuff|junk  |more |
|-----+------+-----|
|word |two   |three|
|many |rows  |that |
|might|extend|past |
|page |bounds|     |
stuff junk more
word two three
many rows that
might extend past
page bounds  

Other blocks (that have issues)

I tried doing these because putting the ATTR_HTML/LATEX stuff is a pain (see Command output), but couldn't make them work properly with LaTeX at the time. There are issues with the way org tries to escape special characters, and I couldn't come up with a solution at the time.

The trouble is I don't remember which special characters are the issue.

TODO Convert old style ATTR versions to these until something breaks, then see if it can be fixed 

#+BEGIN_cmdout
    PID TTY          TIME CMD
1763865 pts/15   00:00:00 bash
1787177 pts/15   00:00:00 ps
#+END_cmdout

    PID TTY          TIME CMD
1763865 pts/15   00:00:00 bash
1787177 pts/15   00:00:00 ps

#+BEGIN_commands
ps
ls
find .
#+END_commands

ps
ls
find .

Here are the same with captions

cmdout
    PID TTY          TIME CMD
1763865 pts/15   00:00:00 bash
1787177 pts/15   00:00:00 ps
commands
ps
ls
find .