Org-mode Teaser Demo

This is the example org-mode file used for the Denver Emacs org-mode introduction talk. Everything in this talk should work without any custom settings or installation with a reasonably recent Emacs version.

Let’s start with a headline, this is kind of like Markdown’s # character:

1 This is an example headline

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

2 Another headline

Nesting headlines is as easy as adding another start

2.1 Nested headline

2.2 Another nested headline

2.2.1 Deeper

2.3 Another headline

2.3.0.1 Deeper…

2.3.0.1.1 Deeper.....

3 Basic markup

You can really go as deep as you want. This is the general building block for org-mode navigation.

Next, let’s talk about some markup

underscores let you underline things
stars add emphasis
slashes are italics
~~pluses are strikethrough~~
equal signs are verbatim text
tildes can also be used

You can generate lists with the - character (seen above), or create numbered ones:

Number one thing
Number two thing
Number three

4 Showing and hiding headlines

You can hide the contents of a headline by putting the point (cursor) or it and hitting TAB.

You can also toggle hiding and showing of all headlines with SHIFT-TAB.

5 Tables

Auto expanding tables are one of the coolest features of org-mode, because tables in Markdown just plain suck. In order to create a new table, you can start typing it manually, or press C-c |, which will prompt for the table’s dimensions.

First Name	Last Name	Years using Emacs
Lee	Hinman	5
Mike	Hunsinger	2
Daniel	Glauser	4
Really-long-first-name-guy	long-last-name-pers	1

6 Org-mode links

In an org-mode file, you can press C-c l to store a pointer to wherever you are in the file. Then, with (or without) text highlighted hit C-C C-l to make it into a link. The example file for Magit If you don’t want to store a pointer (ie, link to a website or something), you can just hit C-c C-l and type or paste the link. To manually create a link, do something like:

The Denver Emacs Meetup Group

Writequit site

Google’s web site

(ignore the *_SRC blocks for now, we’ll get there)

[[http://google.com/][Google]]

You can link to files, images, websites, emails, irc, and all kinds of things.

* Various things you can add in headers

One of the most common uses for org-mode is a sort of “task list” or TODO list. Org-mode supports this by allowing markers in the headline for the state of a task. Let’s look at an example:

** TODO This is a task that needs doing

** TODO Another todo task

[ ] sub task one
[X] sub task two
[ ] sub task three

** Learn about org-mode

*** TODO learn todos

*** TODO learn other stuff

You can toggle each task in a list with the C-c C-c keyboard shortcut.

** DONE I’ve already finished this one

You can change the status of a task by hitting C-c t in the body of a task anywhere, which will prompt for the state to put it in.

You can create as many of these as you’d like, for example (from my own config, use what works best for you, configuring them is a little out of scope right here) here’s what I use:

*** TODO something that needs doing *** DONE something that’s already done *** INPROGRESS something I’m currently doing *** WAITING waiting for someone else before doing anything *** NEEDSREVIEW there’s a PR for this, it needs someone to look at it *** HOLD this is in permanent hold until further notice *** CANCELLED I don’t need this any more *** SOMEDAY I’d like to do this someday in the waaaaay off future

A lot of people just use “TODO” and “DONE” though.

** Adding tags and priorities

You can add tags by putting them surrounded in “:” in the headline. Additionally, priorities

*** Headline with a tag :org:

*** Another tagged headline :turing:denver:

*** Headline with multiple tags :org:emacs:

Tags are just another way of organizing things.

*** [#A] Important task *** [#B] Medium task *** [#C] Non-important task

Again you can configure these, or just use the 3 built in ones. *** TODO [1/3] Task with sub headlines **** TODO Finish thing **** TODO Finish that other thing **** DONE Done with a thing

*** [33%] Task with sub headlines (percent cookie) **** TODO Finish thing **** TODO Finish that other thing **** DONE Done with a thing

* The TODO-planner payoff

So TODOs are all well and good, but what is a really neat feature is when you can easily capture new TODOs and display them easily.

In order to do this, let’s configure a couple of Emacs options in your emacs init:

(require 'org)
;; Setup C-c c to capture new TODOs
(global-set-key (kbd "C-c c") 'org-capture)
;; Setup a key bind for the agenda
(global-set-key (kbd "C-c a") 'org-agenda)
;; Set up agenda to know about our file, you can use a list of files or
;; directories here
(setq org-agenda-files '("~/todo.org"))
;; A new template
(setq org-capture-templates
      '(("t" "Todo" entry (file "~/todo.org")
         "* TODO %?\n%U\n")))

Now, hit C-c c to bring up the capture template list, then t to capture a new TODO item.

Once you’ve captured a few TODOs, you can try out the agenda by hitting C-c a, which will prompt for what agenda you’d like to see, for now hit t to see the TODO list agenda.

* Exporting an org-mode buffer

Org has a lot of export options, they are all contained behind a C-c C-e export backend, exporting to HTML, markdown, plain text, pdf, etc.

* Show off other features of org-mode if we have more time Maybe not in excruciating detail, but we can show off the power and cover it in more detail at a later time:

refiling (org-refile)
source code blocks
org-babel
clocking in/out
table formulas
custom agenda views
capturing notes (not just TODOs)
publishing projects remotely via TRAMP

$a + b$

(defun my/function ()
  "docstring"
  (interactive)
  (progn
    (+ 1 1)
    (message "Hi")))

echo $data > /tmp/foo
for i in `cat /tmp/foo`; do
  echo $i
done

1

2

3

4

echo "hi"

hi

# do some things
echo "stuff"
echo "more stuff"
echo <<hi>>

To enter and edit a block of text, use C-c C-'

Note: a complete list of these features including keyboard shortcuts, links, and descriptions is available on https://github.com/novoid/github-orgmode-tests

This page demonstrates Org-mode features that are (or are not) supported by github which is using an (old) version of org-ruby.

Last GitHub feature render check and last table update: <2020-10-15 Thu>

Feature	status
Text formatting	:WORKS:
Text formatting within other syntax elements	:WORKS:
Lists	:PARTLY:
Headings with TODO items	:FAILS:
Drawers	:FAILS:
blocks (docu)	:PARTLY:
EXAMPLE block	:WORKS:
QUOTE block	:WORKS:
VERSE block	:FAILS:
SRC block	:WORKS:
python	:WORKS:
shell	:WORKS:
ruby	:WORKS:
ditaa	:WORKS:
session with shell and R	:WORKS:
QUOTE block	:WORKS:
HTML block	:FAILS:
LATEX block (docu)	:FAILS:
NOTES block	:FAILS:
comments (docu)	:WORKS:
Noexport tag of heading	:WORKS:noexport:
links (docu)	:PARTLY:
states; TODO items (docu)	:PARTLY:
tags (docu)	:FAILS:
tables simple (docu)	:PARTLY:
tables complex (docu, tutorial)	:PARTLY:
column view (docu)	:FAILS:
dates & time (docu)	:WORKS:
clocking time (docu)	:PARTLY:

* Featuretest

6.1 Text formatting

bold
italic
underline
~~strike through~~
code
commands
http://orgmode.org

small example

6.2 Text formatting within other syntax elements

Within links:

This is an example of some syntax ~~highlighting~~ within links and such.

~gnu~

Table:

Example
http://orgmode.org
Org mode
This is an example of some syntax ~~highlighting~~ within `links` and `such`.

Lists:

Example
- This is an example of some syntax ~~highlighting~~ within links and such.

Headings:

6.2.1 This is an example of some syntax highlighting within `links` and `such`.

6.3 Lists

MISSING:
- Checkbox rendering/alignment
- Reusing same enumerate bullet symbols (dash, numbers, …)

simple list:

Org mode
Lists
[ ] unchecked checkbox
[X] checked checkbox
[-] undecided checkbox (C-u C-u C-c C-c)

enumerate:

Emacs
Org-mode
Lists

mixed with checkboxes:

Clean out garage
1. [ ] get stuff out
  - [ ] be careful with that axe, Eugene
2. [X] get rid of old stuff
  - using eBay?
  - try to use rubbish as birthday presents for family
3. [ ] repaint garage
4. [X] put stuff back in

6.4 Headings with TODO items

MISSING
- display of TODO keywords

6.4.1 TODO Clean out garage [0/4]

6.4.1.1 TODO get stuff out

be careful with that axe, Eugene

6.4.1.2 TODO get rid of old stuff

using eBay?
try to use rubbish as birthday presents for family

6.4.1.3 TODO repaint garage

6.4.1.4 TODO put stuff back in

6.5 Drawers

MISSING:
- rendering of drawers

6.5.1 NEXT Test with category property

6.6 blocks (docu)

including babel (docu)

6.6.1 EXAMPLE block

An example in an EXAMPLE block.
Second line within this block.

This *is* an /example/ of _some_ syntax +highlighting+ within =links= and ~such~.

6.6.2 QUOTE block

Will be wrapped:

An example in an QUOTE block. Second line within this block.

This is an example of some syntax ~~highlighting~~ within links and such.

6.6.3 VERSE block

MISSING:
- rendering of the block

6.6.4 SRC block

6.6.4.1 python

def my_test(myvar: str = 'foo bar'):
    """
    This is an example function.

    @type  myvar: str = 'foo bar': number
    @param myvar: str = 'foo bar': FIXXME
    """

    mynewvar: str = myvar + ' additional content'
    return mynewvar

print("Hello " + my_text('Europe!'))

(message (concat "Hello" "Europe!")) ;; inline comment

some examples are taken from Worg: Introduction to Babel

6.6.4.2 shell

echo "Hello Europe!"
FOO="foo bar"
echo "A test with ${FOO}"
pwd

6.6.4.3 ruby

require 'date'
"This file was last evaluated on #{Date.today}"

6.6.4.4 ditaa

+---------+
| cBLU    |
|         |
|    +----+
|    |cPNK|
|    |    |
+----+----+

6.6.4.5 session with shell and R

cd ~/archive/events_memories && du -sc * |grep -v total

Using result set “directories” from above as “dirs” in R below:

pie(dirs[,1], labels = dirs[,2])

6.6.5 QUOTE block

Will be wrapped:

An example in an QUOTE block. Second line within this block.

This is an example of some syntax ~~highlighting~~ within links and such.

6.6.6 HTML block

MISSING:
- rendering of the block

This is a paragraph with a link within.

6.6.7 LATEX block (docu)

MISSING:
- rendering of the block
- some special characters
Greek characters
- Working outside of block: α β φ
- not working: \LaTeX{} $\varphi$

6.6.8 NOTES block

MISSING:
- rendering of the block

Notes blocks are not standard Org mode. However, org-reveal is using it for handout notes so I would like to include it here.

6.7 comments (docu)

Comment lines:

space hash space:

space space hash space:

Comment block:

6.8 links (docu)

MISSING:
- <<link>>
- following id: links
- custom links
  - without your Emacs config, those links are impossible to follow
  - rendering somehow would be fine
- footnotes

todo: target

# <<link>>

id:myexampleid
~/.zshrc.local
http://orgmode.org
- docu: list of external links
custom links: contact:John Smith
- docu: link abbrevations
footnotes (docu)
- plain ^{:great content here}
- with own label ^mylabel
- reference ^myotherlabel ²

^myotherlabel This is a footnote from reference above. ² This is a footnote with a simple number as label.

Footnotes aren’t working

Footnotes:

^mylabel

great content here

6.8.1 heading with PROPERTIES drawer containing ID

Should have #myexampleid anchor, doesn’t work as of 2021-04-11

Footnotes:

^mylabel

great content here

6.8.2 eading with PROPERTIES drawer containing CUSTOM_ID

Should have #myexamplecustomid anchor, doesn’t work as of 2021-04-11

Footnotes:

^mylabel

great content here

6.9 states; TODO items (docu)

MISSING:
- todo keywords
- dependencies from within drawers

Footnotes:

^mylabel

great content here

6.9.1 making dependencies explicit

Footnotes:

^mylabel

great content here

6.9.1.1 example with chain siblings

Footnotes:

^mylabel

great content here

6.9.1.1.1 NEXT buy bike

Footnotes:

^mylabel

great content here

6.9.1.1.2 take tour

Footnotes:

^mylabel

great content here

6.9.1.1.3 goto hospital

Footnotes:

^mylabel

great content here

6.9.2 priorities (docu)

Footnotes:

^mylabel

great content here

6.9.2.1 TODO [#A] example

Footnotes:

^mylabel

great content here

6.9.2.2 NEXT [#B] example

Footnotes:

^mylabel

great content here

6.9.3 breaking down in subtasks (docu)

Footnotes:

^mylabel

great content here

6.9.3.1 TODO example [1/3] [33%]

Footnotes:

^mylabel

great content here

6.9.3.1.1 DONE subtask 1

Footnotes:

^mylabel

great content here

6.9.3.1.2 TODO subtask 2

Footnotes:

^mylabel

great content here

6.9.3.1.3 TODO subtask 3

Footnotes:

^mylabel

great content here

6.10 tags (docu)

MISSING:
- rendering tags

Footnotes:

^mylabel

great content here

6.10.1 example

Footnotes:

^mylabel

great content here

6.11 tables simple (docu)

MISSING:
- number alignment

Heading1	head2
entry	42
foo	21.7
end	99.99

Footnotes:

^mylabel

great content here

6.12 tables complex (docu, tutorial)

MISSING:
- Tables are concatenated unfortunately and alignment fails.

When	What	USD	EUR
US-Dollar	EUR
1	0.76481836
2012-02-03	Taxi Graz-Airport		18.00
2012-02-03	Taxi Seattle Airport	25.00	19.12
2012-02-13	Taxi	7.00	5.35
2012-02-14	Taxi	8.00	6.12
2012-02-17	Taxi to Airport SeaTac	35.00	26.77
2012-02-22	Taxi Airport-Graz		16.00
			91.36

Footnotes:

^mylabel

great content here

6.13 column view (docu)

MISSING:
- no support for those things

Footnotes:

^mylabel

great content here

6.13.1 example sub-item

Footnotes:

^mylabel

great content here

6.13.2 NEXT [#B] another example

Footnotes:

^mylabel

great content here

6.14 dates & time (docu)

C-c . insert active <2012-04-23 Mon> (with C-u: <2012-04-23 Mon 19:14>)
C-c ! insert inactive [2012-04-23 Mon] (with C-u: [2012-04-23 Mon 19:14])

Footnotes:

^mylabel

great content here

6.15 clocking time (docu)

MISSING:
- drawer information

Footnotes:

^mylabel

great content here

6.15.1 example sub-hierarchy with report

Clock summary at [2012-11-19 Mon 11:17]

Headline	Time
Total time	27:16

Footnotes:

^mylabel

great content here

6.15.1.1 example item

Footnotes:

^mylabel

great content here

6.15.1.2 another item

Footnotes:

^mylabel

great content here

7 MISC Ad-Hoc Testing

This sub-hierarchy is here to test specific stuff.

You can ignore everything starting from here.

Footnotes:

^mylabel

great content here

7.1 Headings

Footnotes:

^mylabel

great content here

7.2 heading with properties

Footnotes:

^mylabel

great content here

7.3 tables

head1	head2	head3
text	42	-----
me@server.example.com	23	:-)
	65

Footnotes:

^mylabel

great content here

7.4 links

direct URL: http://tagstore.org
indirect URL
direct email: me@example.com
indirect email
file link should link to README.org
file + heading link should link to README.org#links – used to work but was broken sometime after 2020-11-01

Footnotes:

^mylabel

great content here

7.5 examples

verse:

quote:

This is an example. Second line. Very long line with many characters showing the wordwrap feature or the not existing word wrap feature

only colon:

This is an example.
    Second line.
Very long line with many characters showing the wordwrap feature or the not existing word wrap feature

non-specific source:

This is an example.
    Second line.
Very long line with many characters showing the wordwrap feature or the not existing word wrap feature

python source:

if VALUE and dummy < 42:
    execute_something("Dummy text", 23)

Footnotes:

^mylabel

great content here

7.6 Underscores_like_this

me_low
2_8
*.org_archive
*.org\_archive
*.org\_archive

Footnotes:

^mylabel

great content here

7.7 Orgmode examples

Das hier ist eine Erklärung von dem Ganzen:

Und in der Org-mode-Datei wird das dann so angewendet:

Footnotes:

^mylabel

great content here

8 Org-mode by Examples

This is a subset(!) of Org-mode basics to demonstrate the main features (sometimes probably more) of this wonderful tool
Find the newest version of this document on https://github.com/novoid/org-mode-workshop

key	description
M	Meta (often: Alt)
C	Ctrl
S	Shift
TAB	Tabulator
RET	Return, Enter, CRLF
UP	arrow: up
DOWN	arrow: down
LEFT	arrow: left
RIGHT	arrow: right
SPC	Space

Footnotes:

^mylabel

great content here

8.1 activating Org-mode

http://orgmode.org/org.html#Activation
http://orgmode.org/worg/org-configs/org-customization-guide.html

Activation of Org-mode (external Tutorial):

(add-to-list 'auto-mode-alist '("\\.\\(org\\|org_archive\\|txt\\)$" . org-mode))
(define-key global-map "\C-ca" 'org-agenda)     ;; by convention: "C-c a" opens agenda
(define-key global-map "\C-cc" 'org-capture)    ;; by convention: "C-c c" captures stuff
(define-key global-map "\C-cl" 'org-store-link) ;; by convention: "C-c l" stores a link to this heading
(setq org-log-done t) ;; if you want to log DONE-states to the :LOGBOOK:-drawer

Org-mode minor mode (structure editing and lists) orgstruct-mode (docu)

Footnotes:

^mylabel

great content here

8.2 Org-mode documentation

http://orgmode.org/org.html is up to date
C-h i (while being in an Org-mode file) gives you a local version :-)

Footnotes:

^mylabel

great content here

8.2.1 In case of Org-mode documentation does not work

For using Org-mode from a local git repository: add following to your configuration:

(add-to-list 'Info-additional-directory-list "~/.emacs.d/<YOURDIRECTORY>/org-mode/doc/")

OR: install Org-mode documentation to your system with:

cd $ORGMODEDIRECTORY && sudo make install-info

Footnotes:

^mylabel

great content here

8.3 text formatting syntax (docu)

bold
italic
underline
~~strike through~~
code
commands
http://orgmode.org

small example

not (yet) working and edge cases:
- *combination*
- /combination/
- *combination*
- _combination_
- *combination*
- C:\a\very\old\DOS\path
- http://orgmode.org
- orgmode-Homepage
- *orgmode* /Homepage/

Footnotes:

^mylabel

great content here

8.4 outlining (docu)

headlines start with asterisks
levels
visibility
- TAB visibility cycling
- S-TAB change buffer visibility
- C-c C-r reveal context
- per-file visibility #+STARTUP: overview and so on: (docu)
- C-u C-u TAB restore startup visibility
motion
- C-c C-n next heading
- C-c C-p previous heading
- C-c C-u one level up
- C-c C-j jump (goto)
- C-c C-f forward same level
- C-c C-b backward same level
- M-x org-goto nifty inerface for searching within an Org-mode buffer
create basic elements
- C-RET new heading below
move elements
- M-UP/DOWN move up/down with subitems
- M-LEFT promote
- M-RIGHT demote
- M-S-LEFT/RIGHT promote/demote with subitems
C-c C-c toggle/modify things (docu)
- checkbox: activate/deactivate, heading: tags, tables: re-calculate, jump footnote and back, update tables, update TODO-count, …
C-c C-x b open sub-tree in separate buffer (org-tree-to-indirect-buffer)

Footnotes:

^mylabel

great content here

8.4.1 Creating

[ ] DEMO: create headings

Footnotes:

^mylabel

great content here