UP | HOME
Last updated: 2023-11-19 Sun 12:15

Org mode syntax
and HTML export examples

This document serves as my personal learning template through examples while referencing actively org-mode manual. This document is available as an:

Org mode, as any markup language, can be written with any text editor. This is written with Vim and vim-orgmode in headless Debian Sid on WSL2 under Windows 11. However, for this orgmode.html to be exported out of orgmode.org file, you’ll also need in that same Debian an emacs installation accompanied with .emacs config and htmlize.el.

This document is based on work by fniessen and 2 while the css-stylesheet used here is based on work by https://gongzhitaao.org/orgcss/.

Table of Contents

Header

The first set of lines of orgmode.org form a header. Each header line starting with #+, configure org-mode’s interpretation of the remainder of the file. Here’s a typical header I use for org-mode files:

#+TITLE: Org mode syntax
#+SUBTITLE: and HTML export examples
#+DATE: <2017-06-04 Tue>
#+AUTHOR: Tuomas Pyyhtiä
#+EMAIL: pyyhttu+org-mode@pm.me
#+DESCRIPTION: Org mode syntax example
#+KEYWORDS: org mode, syntax, quick reference, cheat sheet, html
#+LANGUAGE: en
#+INFOJS_OPT: view:content ltoc:nil path:../org-mode/js/org-info.js
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="../org-mode/css/org.css"/>
#+HTML_LINK_HOME: https://pyyhttu.kapsi.fi
#+HTML_LINK_UP: https://pyyhttu.kapsi.fi/debian/org-mode
#+OPTIONS: toc:nil ':t pri:t num:nil p:nil stat:t tags:t tasks:t tex:t timestamp:t
#+PROPERTY: header-args :eval never-export :exports both :results replace
#+INCLUDE: ../org-mode/macros/org-macros.setup

First set of header lines define the title and sub-title of the page:

#+TITLE: Org mode syntax
#+SUBTITLE: and HTML export examples

Second group of lines set the HTML metadata used in any title pages, headers, footers, etc.:

#+DATE: <2017-06-04 Tue>
#+TITLE: Org mode syntax
#+AUTHOR: Tuomas Pyyhtiä
#+EMAIL: pyyhttu+org-mode@pm.me
#+DESCRIPTION: Org mode syntax example
#+KEYWORDS: org mode, syntax, quick reference, cheat sheet, html

A few other are used exclusively by the html exporter.

#+LANGUAGE: en
#+INFOJS_OPT: view:content ltoc:nil path:../org-mode/js/org-info.js
#+HTML_LINK_HOME: https://pyyhttu.kapsi.fi
#+HTML_LINK_UP: https://pyyhttu.kapsi.fi/debian/org-mode
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="../org-mode/css/org.css"/>

Additional #+OPTIONS handle the structure of table of contents, interpretation of special characters in the buffer, numbering of headings, etc.
#+PROPERTY keyword handles header arguments, how to handle code in exports etc.
Finally #+INCLUDE keyword includes few helpful macros for added an functionality.

#+OPTIONS: toc:nil ':t pri:t num:nil p:nil stat:t tags:t tasks:t tex:t timestamp:t
#+PROPERTY: header-args :eval never-export :exports both :results replace
#+INCLUDE: ../org-mode/macros/org-macros.setup

Headings

Text can be put into the headline. You can create another headline at the same level with another * character:

* Big heading

New chapter.

** Smaller heading

New section within chapter.

*** The smallest heading

New sub-section within section. We need to go deeper.

Big heading

New chapter.

Smaller heading

New section within chapter.

The smallest heading

New sub-section within section. We need to go deeper.

Paragraphs

Paragraphs are separated by at least one empty line:

In mathematics, the Taylor series or Taylor expansion of a function is an infinite sum of terms that are expressed in terms of the function's derivatives at a single point. For most common functions, the function and the sum of its Taylor series are equal near this point. Taylor series are named after Brook Taylor, who introduced them in 1715.

A Taylor series is also called a Maclaurin series when 0 is the point where the derivatives are considered, after Colin Maclaurin, who made extensive use of this special case of Taylor series in the mid-18th century.

In mathematics, the Taylor series or Taylor expansion of a function is an infinite sum of terms that are expressed in terms of the function’s derivatives at a single point. For most common functions, the function and the sum of its Taylor series are equal near this point. Taylor series are named after Brook Taylor, who introduced them in 1715.

A Taylor series is also called a Maclaurin series when 0 is the point where the derivatives are considered, after Colin Maclaurin, who made extensive use of this special case of Taylor series in the mid-18th century.

Line breaks

By entering two consecutive backslashes, \\
you can force a line break
without starting a new paragraph.

By entering two consecutive backslashes,
you can force a line break without starting a new paragraph.

Horizontal rules

For an horizontal line, insert at least 5 dashes: this is some text above an
horizontal rule
-----
and some text below it.

For an horizontal line, insert at least 5 dashes: this is some text above an horizontal rule


and some text below it.

Formatting text

Bold and italic

/Emphasize/ (italics), *strongly* (bold), and */very strongly/* (bold italics).

Markup elements can be nested:

This is /italic text which contains _underlined text_ within it/, whereas _this is
normal underlined text_.

Emphasize (italics), strongly (bold), and very strongly (bold italics).

Markup elements can be nested:

This is italic text which contains underlined text within it, whereas this is normal underlined text.

Markup can span across multiple lines, but by default

*no more than
2 lines.*

*This
is not
bold.*

Org mode does not interpret a marker surrounded by alphanumeric characters as an
emphasis marker. So, you can't (easily) emphasize just part of a word:

Not feas*ible*.

To make the above case to work you'd have to quote with HTML tags:

This is feas@@html:<b>@@ible@@html:</b>@@.

Markup can span across multiple lines, but by default

no more than 2 lines.

This is not bold.

Org mode does not interpret a marker surrounded by alphanumeric characters as an emphasis marker. So, you can’t (easily) emphasize just part of a word:

Not feas*ible*.

To make the above case to work you’d have to quote with HTML tags:

This is feasible.

Monospace, superscript and subscript

Other elements to use sparingly are:

- monospaced typewriter font for ~inline code~
- monospaced typewriter font for =verbatim text=
- +deleted text+ (vs. _inserted text_)
- text with super^{script}, such as 2^{10}
- text with sub_{script}, such as H_{2}O
  • monospaced typewriter font for inline code
  • monospaced typewriter font for verbatim text
  • deleted text (vs. inserted text)
  • text with superscript, such as 210
  • text with subscript, such as H2O

Smart punctuation

If #+OPTIONS: ':t is specified in org-document header, or alternatively (setq org-export-with-smart-quotes t) variable in Emacs configuration file, Org mode will produce typographically correct output in conversion.

- 'single quotes' to curly quotes,
- "straight quotes" to smart quotes,
- --- to em-dashes,
- -- to en-dashes,
- ... to ellipses and
- ' to typographic apostrophe.
  • ’single quotes’ to curly quotes,
  • “straight quotes” to smart quotes,
  • — to em-dashes,
  • – to en-dashes,
  • … to ellipses and
  • ’ to typographic apostrophe.

Lists

Org markup allows you to create bulleted or numbered lists. It allows any combination of the two list types.

Unordered lists

Itemized lists are marked with bullets. Create them with a minus or a plus sign. They are convenient to organize data, and make the document prettier, and easier to read.

- Item with some lengthy text wrapping hopefully across several lines. We add
  a few words to really show the line wrapping.
- Bullet.
  + Bullet.
    * Bullet.
  • Item with some lengthy text wrapping hopefully across several lines. We add a few words to really show the line wrapping.
  • Bullet.
    • Bullet.
      • Bullet.

Checklists

- [X] Checked.
  + [-] Half-checked.
    * [ ] Not checked.
  • [X] Checked.
    • [-] Half-checked.
      • [ ] Not checked.

Note: In above Org code block example I needed to escape the third bullet point (’asterisk’) element with comma (,* [ ]) ensuring it displays correctly as literal code and not rendered in html export into something else. See orgmode.org source file for exact escaped characters and their usage.

Ordered lists

Enumerated lists are marked with numbers or letters like a., A., a) and A), but requires to (setq org-list-allow-alphabetical t) in Emacs configuration file.

Edit: This does not work out-of-the-box, as requires modifications to css file.

1. Arabic (decimal) numbered list item. We add a few words to show the line
   wrapping.
   A. Upper case alpha (letter) numbered list item.
      a. Lower alpha.
      b. Lower alpha.
   B. Upper alpha.
2. Number.
  1. Arabic (decimal) numbered list item. We add a few words to show the line wrapping.
    1. Upper case alpha (letter) numbered list item.
      1. Lower alpha.
      2. Lower alpha.
    2. Upper alpha.
  2. Number.

You can have ordered lists with jumping numbers:

2. [@2] We start with point number 2.
3. Automatically numbered item.
  1. We start with point number 2.
  2. Automatically numbered item.

Definition lists

Labeled, multi-line lists.

- First term to define ::
     Definition of the first term. We add a few words to show the line wrapping,
     to see what happens when you have long lines.
- Second term ::
     Explication of the second term with *inline markup*.

     In many paragraphs.
First term to define
Definition of the first term. We add a few words to show the line wrapping, to see what happens when you have long lines.
Second term

Explication of the second term with inline markup.

In many paragraphs.

Separating lists

Adjacent ordered lists sometimes like to fuse. To force the start of a new ordered list, offset the two lists by two empty lines, or by a #-comment:

1. apples
2. oranges
3. bananas
# comment
1. carrots
2. tomatoes
3. celery
  1. apples
  2. oranges
  3. bananas
  1. carrots
  2. tomatoes
  3. celery

Unordered lists, however, I need to be separated with a line break:

- apples
- oranges
- bananas
\\
- carrots
- tomatoes
- celery
  • apples
  • oranges
  • bananas


  • carrots
  • tomatoes
  • celery

NEXT Tables

Note-to-self: To ease up creating tables, check if vim-table-mode plugin creates org compatible tables (check via export to html).

Tables are one of the most refined areas of the Org mode syntax. They are very easy to create and to read.

Simple table

| Cell in column 1, row 1 | Cell in column 2, row 1 |
| Cell in column 1, row 2 | Cell in column 2, row 2 |
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2

Org tables have cells of at most one line long: there is no such thing as a multi-line table cell in Org.

Column formatting

Columns are automatically aligned:

  • Number-rich columns to the right, and
  • String-rich columns to the left.

Table with caption and aligned cells

Table captions can be added with #+CAPTION: Description. Table alignment: If you want to override the automatic alignment, use <r>, <c> or <l>.

#+CAPTION: Table with aligned columns
|          <r>            | <c>                     | <l>                     |
|            1            | 2                       | 3                       |
|        Right            | Center                  | Left                    |
| Cell in column 1, row 3 | Cell in column 2, row 3 | Cell in column 1, row 3 |
Table 1: Table with aligned columns
1 2 3
Right Center Left
Cell in column 1, row 3 Cell in column 2, row 3 Cell in column 3, row 3

Header row

You can create tables with an header row (by using an horizontal line of dashes to separate it from the rest of the table).

#+CAPTION: Table with an header row
| Name of column 1 | Name of column 2 | Name of column 3 |
|------------------+------------------+------------------|
| Top left         | Top middle       |                  |
|                  |                  | Right            |
| Bottom left      | Bottom middle    |                  |
Table 2: Table with an header row
Name of column 1 Name of column 2 Name of column 3
Top left Top middle  
    Right
Bottom left Bottom middle  

A very long table

To test “sticky table headers”…

| Name of column 1 | Name of column 2 | Name of column 3 |
|------------------+------------------+------------------|
|         Top left | Top middle       |                  |
|                2 |                  |                  |
|                3 |                  |                  |
|                4 |                  |                  |
|                5 |                  |                  |
|                6 |                  |                  |
|                7 |                  |                  |
|                8 |                  |                  |
|                9 |                  |                  |
|               10 |                  |                  |
|               11 |                  |                  |
|               12 |                  |                  |
|               13 |                  |                  |
|               14 |                  |                  |
|               15 |                  | Right            |
|               16 |                  |                  |
|               17 |                  |                  |
|               18 |                  |                  |
|               19 |                  |                  |
|               20 |                  |                  |
|               21 |                  |                  |
|               22 |                  |                  |
|               23 |                  |                  |
|               24 |                  |                  |
|               25 |                  |                  |
|               26 |                  |                  |
|               27 |                  |                  |
|               28 |                  |                  |
|               29 |                  |                  |
|      Bottom left | Bottom middle    |                  |
Name of column 1 Name of column 2 Name of column 3
Top left Top middle  
2    
3    
4    
5    
6    
7    
8    
9    
10    
11    
12    
13    
14    
15   Right
16    
17    
18    
19    
20    
21    
22    
23    
24    
25    
26    
27    
28    
29    
Bottom left Bottom middle  

NEXT Table placement

#+ATTR_HTML: :border 2 :rules all :frame border :style float:left;
| a | b |
| 1 | 2 |
a b
1 2
#+ATTR_LATEX: :center nil
| a | b |
| 1 | 2 |
a b
1 2

XXX Different from the following:

| a | b |
| 1 | 2 |
a b
1 2

NEXT Align tables on the page

Left

Here is a table on the left side:

,#+LATEX: \noindent ,#+ATTRLATEX: :center nil

a b c
1 2 3
4 5 6

,#+LATEX: \hfill

The noindent just gets rid of the indentation of the first line of a paragraph which in this case is the table. The hfill adds infinite stretch after the table, so it pushes the table to the left.

Center

Here is a centered table:

a b c
1 2 3
4 5 6

Right

And here’s a table on the right side:

a b c
1 2 3
4 5 6

Here the hfill adds infinite stretch before the table, so it pushes the table to the right.

Table size

#+ATTR_HTML: :width 100%
| Cell in column 1, row 1 | Cell in column 2, row 1 |
| Cell in column 1, row 2 | Cell in column 2, row 2 |
Cell in column 1, row 1 Cell in column 2, row 1
Cell in column 1, row 2 Cell in column 2, row 2

CSV

You can fill a table from a CSV file using R commands.

Links

External links

See http://www.pirilampo.org (automatic!) and the
Org mode Web site.

See http://www.pirilampo.org (automatic!) and the Org mode Web site.

Relative links

[[../org-mode/orgmode.html][Home]]

Home

Email links

Image links

To get image links, put a link to a file in the description.

Clicking on the image org-mode-unicorn.png leads to the Org mode home page.

Internal links

Inline anchors

Anchors are used to specify hypertext link targets.

Inline anchors make arbitrary content referenceable.

Internal cross references

See:

Remote references

Linking to a table is done by a #+NAME: line before the table.

Here is a named table.

#+NAME: my target
| x | y |
| 1 | 2 |
x y
1 2
I can now reference to it with its name. Like this:
my target

I can reference it with its name. Like this: 3

Extensions that define new hyperlinks targets

Images

Inline pictures

Images are simply shown with: [​[file:images/Org-mode-unicorn.svg]]

Images are simply shown with: Org-mode-unicorn.svg

You can also point to an image with text link: [​[file:images/Org-mode-unicorn.svg][Unicorn picture]].

You can also point to an image with text link: Unicorn picture.

Images itself can also contain links, HTML-attributes, and a caption, which can be exported:

#+caption: Taylor Series
#+ATTR_HTML: :alt Obligatory xkcd comic depicting complexity of Taylor series function :title The Taylor series should have been canceled after the first term.
[​[https://m.xkcd.com/2605/][file:images/taylor_series.png]]

Images itself can also contain links, HTML-attributes, and a caption, which can be exported:

Obligatory xkcd comic depicting complexity of Taylor series function

Figure 1: Taylor Series

Image attributes and values

Some of the most used image attributes:

Attribute Usage and example
:alt Alternative text. alt: Obligatory xkcd comic depicting complexity of Taylor series function
:title Visible on mouse hover. :title The Taylor series should have been canceled after the first term.
:height Height in percentages. :height 35%
:width Width in pixels. :width 200
:style float To align images so that text succeeds them. :style float:left;margin:20px 20px 20px 0px;
:align To align images so that paragraphs succeed them. :align:left;margin:0px 50px 50px 50px;
:border Border. :style border:2px solid black;
:bordercolor  
:hspace  
:vspace  

A full list of available HTML image tags linked to at org-tutorials.

org-mode-unicorn.png

Place images side by side: XXX

See also on how to resize image.

Image alignment (using positioning)

Books usually align/float images on the right/left of the contents.

Image is left aligned

Image is right aligned

Image is centered

Figures

To define images that will be treated as book illustrations (figures) and automatically labeled and numbered, use XXX.

Videos

Videos can’t be added directly.

Though, you can add an image with a link to the video like this:

bigblow.png

Admonitions

Admonitions (contextual backgrounds) are statements taken out of the content’s flow and labeled with a title.

Common admonitions are:

  1. note
  2. warning
  3. tip
  4. caution
  5. important
  6. comment

(Most themes style only note and warning specially.)

Note

#+begin_note
=/usr/bin/which=: this version of `which' is deprecated; use ~command -v~ in scripts instead.
#+end_note

/usr/bin/which: this version of `which’ is deprecated; use command -v in scripts instead.

Warning

#+begin_warning
Do not edit files in =/etc/sudoers.d= directly, but use ~visudo~. Otherwise
you risk locking out all your users!
#+end_warning

Do not edit files in /etc/sudoers.d directly, but use visudo. Otherwise you risk locking out all your users!

Comment

Not an admonition per se, but '#+BEGIN_COMMENT' ... '#+END_COMMENT' is handy for metadocumenting larger sections in the .org-document:

#+begin_comment
Regions surrounded by ‘#+BEGIN_COMMENT’ … ‘#+END_COMMENT’ are not HTML-exported.
See the actual comment yourself in source org-file, or exact usage in
org-manual.
#+end_comment

Aligned text

#+begin_left
This text is \\
aligned to the left!
#+end_left

This text is
aligned to the left!

#+begin_center
This text is \\
centered!
#+end_center

This text is
centered!

#+begin_right
This text is \\
aligned to the right!
#+end_right

This text is
aligned to the right!

Prose excerpts

Abstract

#+begin_abstract works out of the box with LaTeX exports, although HTML with CSS can support it as well:

#+begin_abstract
In this Method of Increments, I consider quantities as increased by Increments or
diminished by Decrements, and between the given relations of the Integral [whole]
quantities, I seek the relations between the Increments, and from given relations between
Increments, I seek the Integral quantities themselves in turn. The uses of these methods in
mathematical matters is widely known ; and moreover it is shown to the greatest effect in
these circumstances where all the properties of Fluxions may hence be easily
derived.[...]
#+end_abstract

In this Method of Increments, I consider quantities as increased by Increments or diminished by Decrements, and between the given relations of the Integral [whole] quantities, I seek the relations between the Increments, and from given relations between Increments, I seek the Integral quantities themselves in turn. The uses of these methods in mathematical matters is widely known ; and moreover it is shown to the greatest effect in these circumstances where all the properties of Fluxions may hence be easily derived.[…]

Example blocks

An Org mode block is a region of text surrounded by #+BEGIN_ūĚí≥ ‚Ķ #+END_ūĚí≥:

#+BEGIN_EXAMPLE
You can include literal examples that should not be subjected to markup. Such
examples are typeset in monospace, so this is well suited for source code and
similar examples.
#+END_EXAMPLE
You can include literal examples that should not be subjected to markup. Such
examples are typeset in monospace, so this is well suited for source code and
similar examples.
: Short examples can also be created with a colon and a space.
Short examples can also be created with a colon and a space.

Quote

Use the quote block for content that doesn’t require the preservation of line breaks.

#+begin_quote
Let us change our traditional attitude to the construction of programs:
Instead of imagining that our main task is to instruct a computer what to do,
let us concentrate rather on explaining to human beings what we want a
computer to do.

The practitioner of literate programming can be regarded as an essayist, whose
main concern is with exposition and excellence of style. Such an author, with
thesaurus in hand, chooses the names of variables carefully and explains what
each variable means. He or she strives for a program that is comprehensible
because its concepts have been introduced in an order that is best for human
understanding, using a mixture of formal and informal methods that reinforce
each other.

-- Donald Knuth
#+end_quote

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.

– Donald Knuth

Verse

In a verse, there is an implicit line break at the end of each line, and indentation is preserved. Here’s a 5-7-5 haiku:

#+begin_verse
      Fatass Cartman was
  Not on the school bus today.
      What a big fat turd!
#+end_verse

    Fatass Cartman was
Not on the school bus today.
    What a big fat turd!

Block quotes with their own class attribute

NEXT Block quote with optional attribution line

Try with css from https://stackoverflow.com/questions/16712501/org-mode-epigraph

Three Rings for the Elven-kings under the sky,
Seven for the Dwarf-lords in their halls of stone,
Nine for the Mortal Men doomed to die,
One for the Dark Lord on his dark throne
In the Land of Mordor where the Shadows lie.
One Ring to rule them all, One Ring to find them,
One Ring to bring them all and in the darkness bind the
In the Land of Mordor where the Shadows lie.

Non-breaking space

Insert the Unicode character 00A0 to add a non-breaking space.

FIXME Or add/use an Org entity? Or use tilde?

Substitutions

NEXT General replacements

#+MACRO: longtext-dish Lopado­temacho­selacho­galeo­kranio­leipsano­drim­hypo­trimmato­silphio­karabo­melito­katakechy­meno­kichl­epi­kossypho­phatto­perister­alektryon­opte­kephallio­kigklo­peleio­lagoio­siraio­baphe­tragano­pterygon

A fictional dish called {{{longtext-dish}}} was mentioned in Aristophanes' 391 B.C. comedy Assemblywomen.

A fictional dish called Lopado¬≠temacho¬≠selacho¬≠galeo¬≠kranio¬≠leipsano¬≠drim¬≠hypo¬≠trimmato¬≠silphio¬≠karabo¬≠melito¬≠katakechy¬≠meno¬≠kichl¬≠epi¬≠kossypho¬≠phatto¬≠perister¬≠alektryon¬≠opte¬≠kephallio¬≠kigklo¬≠peleio¬≠lagoio¬≠siraio¬≠baphe¬≠tragano¬≠pterygon was mentioned in Aristophanes’ 391 B.C. comedy Assemblywomen.

Emacs comes with these built in macros, some more common used are:

{{{title}}}\\
{{{author}}}\\
{{{email}}}\\
{{{date}}}\\
{{{date("%Y-%m-%d")}}}\\
{{{time("%H:%M:%S")}}}\\

Org mode syntax Org mode syntax Org mode syntax Org mode syntax
Tuomas Pyyhtiä Tuomas Pyyhtiä Tuomas Pyyhtiä
pyyhttu+org-mode@pm.me
<2017-06-04 Sun>
“2017-06-04”
“12:16:13”

Styled references

#+MACRO: color @@html:<span style="color: $1">$2</span>@@

{{{color(blue, This text is colored in blue.)}}}

{{{color(red, This other text is in red.)}}}

This text is colored in blue.

This other text is in red.

Other macros from https://github.com/fniessen/org-macros e.g.:

Keyboard macro:
Pressing {{{kbd(C-x)}}}{{{kbd(f)}}} -- means holding both Control /and/ x, release both, and press f.

Keyboard macro: Pressing C-xf – means holding both Control and x, release both, and press f.

Background color macro spans the whole line and can be combined with text alignment:

#+begin_center
{{{bgcolor(red, DANGER! MINE FIELD!)}}}
#+end_center

Common color names are supported by most Org exporters (HTML, LaTeX):

{{{bgcolor(red, red)}}}
{{{bgcolor(orange, orange)}}}
{{{bgcolor(yellow, yellow)}}}
{{{bgcolor(green, green)}}}
{{{bgcolor(blue, blue)}}}
{{{bgcolor(purple, purple)}}}
{{{bgcolor(violet, violet)}}}

You can also use hexadecimal color codes:

{{{bgcolor(#FF0000, #FF0000)}}}
{{{bgcolor(#00FF00, #00FF00)}}}
{{{bgcolor(#0000FF, #0000FF)}}}

DANGER! MINE FIELD!

Common color names are supported by most Org exporters (HTML, LaTeX):

red
orange
yellow
green
blue
purple
violet

You can also use hexadecimal color codes:

#FF0000
#00FF00
#0000FF

Macros can also be applied to foreground text.

Here’s Ned Flanders singing his LP of Dreamcoat:

#+BEGIN_VERSE
How I love my coat of many colors.
It was {{{color(red, red)}}} and {{{color(yellow, yellow)}}} and {{{color(green, green)}}} and {{{color(brown, brown)}}},
And {{{color(#ff2d00, scarlet)}}} and {{{color(black, black)}}} and {{{color(#ff8f00, ocher)}}} and {{{color(#fd8340, peach)}}},
And {{{color(#ff003e, ruby)}}} and {{{color(olive, olive)}}} and {{{color(violet, violet)}}} and {{{color(#d18b10, fawn)}}}...
...And {{{color(#d399fa, lilac)}}} and {{{color(gold, gold)}}} and {{{color(chocolate, chocolate)}}} and {{{color(#663f56, mauve)}}},
And {{{color(#eed989, cream)}}} and {{{color(crimson, crimson)}}} and {{{color(silver, silver)}}} and {{{color(#ee89af, rose)}}},
And {{{color(azure, azure)}}} and {{{color(#ebf131, lemon)}}} and {{{color(#954b23, russet)}}} and {{{color(grey, grey)}}}...
...And {{{color(purple, purple)}}} and {{{color(white, white)}}} and {{{color(pink, pink)}}} and {{{color(orange, orange)}}},
And {{{color(red, red)}}} and {{{color(yellow, yellow)}}} and {{{color(green, green)}}} and {{{color(brown, brown)}}},
And {{{color(#ff2d00, scarlet)}}} and {{{color(black, black)}}} and {{{color(#ff8f00, ocher)}}} and {{{color(#fd8340, peach)}}},
#+END_VERSE

How I love my coat of many colors.
It was red and yellow and green and brown,
And scarlet and black and ocher and peach,
And ruby and olive and violet and fawn
…And lilac and gold and chocolate and mauve,
And cream and crimson and silver and rose,
And azure and lemon and russet and grey
…And purple and white and pink and orange,
And red and yellow and green and brown,
And scarlet and black and ocher and peach,

Highlight macro spans only the width of the text:

{{{hl(POLICE LINE DO NOT CROSS)}}}

{{{highlight(red, red)}}}
{{{highlight(orange, orange)}}}
{{{highlight(green, green)}}}
{{{highlight(blue, blue)}}}
{{{highlight(purple, purple)}}}
{{{highlight(violet, violet)}}}

POLICE LINE DO NOT CROSS

red orange green blue purple violet

Lorem Ipsum macro:

{{{loremipsum}}}

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Special symbols

We also use substitutions to include some of the widely used Unicode characters (like ©, converted from text characters to its typographically correct entity).

- \Agrave \Aacute
- Dash: \ndash \mdash
- Marks: \iexcl \iquest
- Quotations: \laquo \raquo
- Miscellaneous: \para \ordf
- Currency: \cent \EUR \yen \pound
- The Greek letters \alpha, \beta, and \gamma are used to denote angles.
- Science: \pm \div
- Arrows: \to \rarr \larr \harr \rArr \lArr \hArr
- Function names: \arccos \cos
- Signs and symbols: \bull \star
- Smilies: \smiley \sad
- Suits: \clubs \spades
- [...]
  • À Á
  • Dash: – —
  • Marks: ¡ ¿
  • Quotations: « »
  • Miscellaneous: ¶ ª
  • Currency: ¢ € ¥ £
  • The Greek letters α, β, and γ are used to denote angles.
  • Science: ± ÷
  • Arrows: → → ← ↔ ⇒ ⇐ ⇔
  • Function names: arccos cos
  • Signs and symbols: • *
  • Smilies: ☺ ☹
  • Suits: ♣ ♠
  • […]

See exhaustive list of symbol names supported from here. For the rest, use Unicode.

Exporting Unicode characters to html should work since the charset is declared as utf-8. However, do note support between browsers vary.

Org mode also exports HTML entities, decimals and hexadecimals into literal HTML using an export block:

#+BEGIN_EXPORT html
<td>
<ul>
<li>Using HTML entity to display &spades;</li>
<li>Using decimal to display &#9824;</li>
<li>Using hexadecimal to display &#x2660;</li>
</ul>
</td>
#+END_EXPORT
  • Using HTML entity to display ♠
  • Using decimal to display ♠
  • Using hexadecimal to display ♠

Source code

Code blocks

The source code blocks support syntax highlighting (cpp), row numbers (-n) and highlight referrals (ref:). Code block syntax highlighting in Org mode’s HTML export depends on the htmlize library.

#+begin_src cpp -n -r
// Your First C++ "Hello World!"            (​ref:comment)

#include <iostream>                         (​ref:preprocessor)

int main() {                                (​ref:main)
    std::cout << "Hello World!";
    return 0;
}
#+end_src

Where,

~//~ denotes a comment on line [​[(comment)]]

The [​[(preprocessor)][~#include~]] is a preprocessor directive used to include files in our program.

~int main() {...}~: A valid C++ program must have the [​[(main)][main()]] function.
1: // Your First C++ "Hello World!"
2: 
3: include <iostream>
4: 
5: int main() {
6:     std::cout << "Hello World!";
7:     return 0;
8: }

Where,

// denotes a comment on line 1

The #include is a preprocessor directive used to include files in our program.

int main() {...}: A valid C++ program must have the main() function.

Note: In above Org code block example I needed to escape some elements with comma (,#+end_src) and with zero width spaces ((<200b>ref:comment)) ensuring those elements were displaying correctly as literal code and not rendered in html export into something else. See orgmode.org source file for exact escaped characters and their usage.

NEXT Inline code

If you have done $ sudo aptitude install r-base-core then you can evaluate:

You can also evaluate code inline as follows: 1 + 1 is src_R{1 + 1}.

You can also evaluate code inline as follows: 1 + 1 is .

Edit: Code evaluating does not seem to work in exported results. This has something to do with this documents header argument: #+PROPERTY: header-args :eval never-export :exports both :results replaced Google emacs evaluate code and also see: https://orgmode.org/manual/Exporting-Code-Blocks.html and https://orgmode.org/manual/Literal-Examples.html#FOOT115

Editedit: setup first R language to work https://www.r-bloggers.com/2022/12/using-emacs-for-r/ and then research https://emacs.stackexchange.com/questions/33103/no-org-babel-execute-function-for-calc Get R first to evaluate anything with c-c c-c Also see: https://stackoverflow.com/questions/44977043/how-to-execute-inline-source-blocks-in-an-org-mode-table

Source mode

The following language strings are currently recognized:

ABC, Asymptote, Awk, C, C++, Calc, Clojure, comint, Coq, CSS, D, Ditaa, Dot (Graphviz), ebnf, Emacs Lisp, Forth, Fortran, Gnuplot, Haskell, Io, J, Java, Javascript, LaTeX, Ledger, Lilypond, Lisp, Make, Matlab, Maxima, Mscgen, Objective Caml, Octave, Org, Perl, Picolisp, PlantUML, Processing, Python, R, Ruby, Sass, Scala, Scheme, Screen, Sed, shell, Shen, SQL, SQLite, Stan, Vala, Contributed, Language, Eukleides, Fomus, Groovy, Julia, Mathematica, Mathomatic, OZ, Stata, Tcl, Emacs Package, Language, Axiom, HTML, Neo4j, Elixir, http request, iPython, Kotlin, Lisp Flavored Erlang, MongoDB, Prolog, rec, Standard ML, Google Translate and Typescript.

Diagrams

Diagrams or flowcharts can be “drawn” in ascii art with Vim addons such as DrawIt and vim-boxdraw, as well as utilizing :he virtualedit. Export happens calling emacs export via vim-orgmode and ditaa. Here’s a flowchart from xkcd:

      +-------+
      | Start |
      +---+---+
          |
          v
+-------------------+
|                   |
|                   |
|      Do you       |Yes                                        +------+Yes
|    understand     +------------------------------------------>| Good +-------------+
|   flow charts?    |                                           +------+             |
|  {c}              |                                               ^                |
|                   |                                               |                v                  +----------------+
+-------------------+                                               |          +------------+           |                |
          | No                                                      |          |            | 6 drinks  | Hey, I should  |
          |                                                         |          |   Let's go +---------->| try installing |
          |                                                         |          |   drink.   |           |   FreeBSD!     |
          v                                                         |          |            |           |                |
+-------------------+                    +-------------------+      |          +------------+           +----------------+
|                   |                    |                   |      |                ^
|                   |                    |                   |      |                |
|       Okay.       |Yes                 |  ...And you can   |Yes   |                |
|    You see the    +------------------->+    see the ones   +------+                |
|   line labeled    |                    |    labeled "no"?  |                 +-----+------+
|       "yes"? {c}  |                    |   {c}             |                 |  Screw it. |
|                   |                    |                   |                 +------------+
+-------------------+                    +---------+---------+                       ^
          | No                                     |No                               |
          |                                        v                                 |
          |                              +-------------------+                       |
          v                              |                   |                +------+-------+
+-------------------+                    |                   |                |              |
|                   |                    |      But you      |Yes             | (That wasn't |
|                   |       +-------+    |   just followed   +--------------->+ a question). |
|     But you       |Yes    |       |    |    them twice!    |                |              |
|   see the ones    +------>| Wait, |    |    {c}            |                +--------------+
|     labeled       |       | What? |    |                   |                       ^
|       "no"?       |       |       |    +---------+---------+                       |
|  {c}              |       +-------+              |No                               |
+---------+---------+                              +---------------------------------+
          |No           +--------+
          v             |        |
     +---------+        | I hate |
     | Listen. |------->|  you.  |
     +---------+        |        |
                        +--------+

diagram.png

    /-----------+        /---------\
    |    PLC    |        |         |
    |  Network  +<------>+   PLC   +<---=---------+
    |    cRED   |        |  c707   |              |
    +-----------/        \----+----/              |
                              ^                   |
                              |                   |
                              |  +----------------|-----------------+
                              |  |                |                 |
                              v  v                v                 v
      +----------+       +----+--+--+      +-------+---+      +-----+-----+       Windows clients
      |          |       |          |      |           |      |           |      +----+      +----+
      | Database +<----->+  Shared  +<---->+ Executive +<-=-->+ Operator  +<---->|cYEL| . . .|cYEL|
      | {s} cBLU |       |  Memory  |      | {io} cPNK |      | Server    |      |    |      |    |
      +--+----+--+       |{d} cGRE  |      +------+----+      |   c707    |      +----+      +----+
         ^    ^          +----------+             ^           +-------+---+
         |    |                                   |
         |    +--------=--------------------------+
         v
+--------+--------+
|                 |
| Millwide System |            -------- Data ---------
| cBLU            |            --=----- Signals ---=--
+-----------------+

integration.png

Not all shape selector tags are documented on the ditaa site, document these as examples.

The above ditaa ($sudo aptitude install ditaa) diagrams require modifications to .emacs config. Do (ctrl-f in file ditaa to see what those modifications are and match to your setup accordingly. My setup: WSL2, headless Debian Sid under Windows 11.

Then code block above needs to have :exports results: https://orgmode.org/manual/Exporting-Code-Blocks.html

Pay attention also to document header #+PROPERTIES, what should they be for evaluation to pass through silently?

Math

Inline math expressions

For inline math expressions, use the parentheses notation \(...\):

The formula \(a^2 + b^2 = c^2\) has been discovered by Pythagoras.

Let \(a=\sin(x) + \cos(x)\). Then \(a^2 = 2\sin(x)\cos(x)\) because \(\sin^2x +
\cos^2x = 1\).

The formula \(a^2 + b^2 = c^2\) has been discovered by Pythagoras.

Let \(a=\sin(x) + \cos(x)\). Then \(a^2 = 2\sin(x)\cos(x)\) because \(\sin^2x + \cos^2x = 1\).

Math expressions in display mode

For mathematical expressions which you want to make stand out, centered on their own lines, use \[...\]:

The /Taylor series:/

\[
f(a)+{\frac {f'(a)}{1!}}(x-a)+{\frac {f''(a)}{2!}}(x-a)^{2}+{\frac {f'''(a)}{3!}}(x-a)^{3}+\cdots ,
\]

where /n!/ denotes the factorial of /n/. In the more compact sigma notation, this can be written as

\[ \sum _{n=0}^{\infty }{\frac {f^{(n)}(a)}{n!}}(x-a)^{n} \]

The Taylor series:

\[ f(a)+{\frac {f'(a)}{1!}}(x-a)+{\frac {f''(a)}{2!}}(x-a)^{2}+{\frac {f'''(a)}{3!}}(x-a)^{3}+\cdots , \]

where n! denotes the factorial of n. In the more compact sigma notation, this can be written as

\[ \sum _{n=0}^{\infty }{\frac {f^{(n)}(a)}{n!}}(x-a)^{n} \]

If your LateX is rusty, you can copy mathematical expressions (e.g. from wikipedia) using ctrl-c and paste them into online LaTeX editor to get proper code. You can also produce real-time LaTeX using Neo(Vim).

Include Org files

You can include another Org file and skip its title by using the :lines argument to #+INCLUDE:

#+INCLUDE: "chapter1.org" :lines "2-"

File inclusion, through INCLUDE keywords, is an export-only feature.

Footnote

It is possible to define named footnotes[fn:myfootnote], or ones with automatic
anchors[fn:2]. Scroll to the bottom to see the footnotes.

It is possible to define named footnotes1, or ones with automatic anchors2. Scroll to the bottom to see the footnotes.

Useful extensions

** NEXT [#A] H2 Title with TODO state, priority and a tag  :online:
*** FOLLOWUP [#B] H3 Title with different TODO state, priority and several tags  :computer:write:
**** DONE [#C] H4 title with closed TODO state and priority
:LOGBOOK:
    - State "TODO"        ->  "DONE"       [2014-01-16 Thu 09:52]
:END:

Priority is displayed if =#+OPTIONS: pri:t= or priority cookie
=(org-export-with-priority)= is set.

By default, ~DONE~ actions will be collapsed and drawers (notice ~:LOGBOOK:~
in Org code block?) are not exported to HTML, unless =#+OPTIONS: d:t= is
defined.

NEXT [A] H2 Title with TODO state, priority and a tag   online

FOLLOWUP [B] H3 Title with different TODO state, priority and several tags   computer write

  • DONE [C] H4 title with closed TODO state and priority

    Priority is displayed if #+OPTIONS: pri:t or priority cookie (org-export-with-priority) is set.

    By default, DONE actions will be collapsed and drawers (notice :LOGBOOK: in Org code block?) are not exported to HTML, unless #+OPTIONS: d:t is defined.

Timestamps

An inactive timestamp does not cause an agenda entry
[2014-01-16 Thu] while active <2014-01-16 Thu> does.

An inactive timestamp does not cause an agenda entry [2014-01-16 Thu] while active <2014-01-16 Thu> does.

[A] TODO Read GTD book

By default, all (active) entries will be expanded at page load, so that their contents is visible.

That can be changed by adding such a line (into your Org document):

#+HTML_HEAD: <script> var HS_STARTUP_FOLDED = true; </script>

[B] TODO Apply GTD methodoloy

This section will be collapsed when loading the page because the entry has the value hsCollapsed for the property :HTML_CONTAINER_CLASS:.

Powerful, no?

Some note   computer write

You can add tags to any entry, and hightlight all entries having some specific tag by clicking on the buttons made accessible to you in the “Dashboard”.

Weekly review   computer

Now, you can even make your weekly review in the HTML export… Press the r-key to start entering the “review mode” where all but one active entry are collapsed, so that you can really focus on one item at a time!

Bigblow extension

The string fixme (in upper case) gets replaced by a “Fix Me!” image:

FIXME Delete this...

FIXME Delete this…

Citations

Cross-referenced to bibliography.

Appendix

Special sections.

Index

Index (or list of acronyms).

  • Write index entries

Note that multi-entry terms generate separate index entries.

  • Place the index at the desired location
  • Produce the index by updating org-latex-pdf-process

Bibliography

The bibliography…

  • Eric Steven Raymond. The Art of Unix Programming. Addison-Wesley. ISBN 0-13-142901-9.

Glossary

A glossary term
The corresponding (indented) definition.
A second glossary term
The corresponding (indented) definition.

For additional reading / notes

Footnotes:

1

Footnotes are extensively used in large documents.

2

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Tuomas Pyyhtiä / Validate Vim 8.2 (vim-orgmode 0.6.0)