SiteMap Search ElispArea HowTo Glossary RecentChanges News Problems Suggestions

This page needs attention!

OrgMode

Overview

Org-mode is an Emacs mode for note keeping, project planning, TODO lists and authoring. It is included from Emacs 22.1 onward as default.

Org-mode’s manual, compact guide, the community maintained Worg (which includes tutorial, ideas, code snippets, etc.,) and can be accessed at its homepage. Paperback manual is also available. El Manual de Org, traduccioón al español para 23.1.

Features

Download and Install

The development version is at:

    git clone git://repo.or.cz/org-mode.git

There is a Ubuntu repository with the latest for non-cvs Emacs. Add the following to your /etc/apt/sources.list:

    deb http://ppa.launchpad.net/hexmode/ubuntu gutsy main
    deb-src http://ppa.launchpad.net/hexmode/ubuntu gutsy main

Texts on using org-mode

David O’Toole has written a general tutorial with screenshots. It has been translated into Chinese, French, Hungarian, Japanese and Korean. Worg has many tutorials on specific features. Charles Cave has has written on using date and times. Bernt Hansen describes his use and customizations of Org-mode in 70(!) pages long document, which assumes basic familiarity with Org.

One of the major influences in 2006/2007 on task organization has been the book Getting Things Done (GTD). Using Org-mode for GTD has been described by Charles Cave and a modest example configuration has been given here.

Both John Wiegley and Sacha Chua have described day planner usage. Another piece by SachaChua is "A day in the life with Org".

Publishing

You can publish to HTML using ‘C-c C-e h’, or you can use BhlMode for LaTeX or HTML output. Just switch modes before exporting (‘M-x bhl-mode’). BhlMode should automatically recognize the asterisks as marking sections and subsections. See EmacsOutlineToHtml for other alternatives.

org-publish.el (this comes in the latest version of org-mode) by DavidOtoole is a publishing management system for creating websites composed of all the files within a project (including OrgMode files, images, and source code, if desired).

new exporter/publish framework

Conflicts

If you’re using WindMove, CuaMode or MTorus (with default keybindings), you might want to disable the Org Mode keybindings for Shift+arrow keys:

    (setq org-replace-disputed-keys t)

(This need to be done before org.el is loaded, or requires a restart of Emacs to be effective.)

This will result in the following replacements:

If AllOut from Emacs 21 is loaded before org.el, you will be getting a Wrong type argument ((keymapp nil)) error. This was fixed in Emacs 22.

If you are forced to use Emacs 21, either install a newer version of allout.el, or make sure that org.el is loaded before allout.el. For example, use (require 'org) before requiring allout.

If you’re using session.el (EmacsSession), you need to excempt a circular data structure from saving:

    (add-to-list 'session-globals-exclude 'org-mark-ring)

If you’re using Emacs 23 and Org 7.5, then you can also have some pseudo-compatability while maintaining CUA support with Lisp:org-cua-dwim.el

External Data Sources

If you publish external sources to org mode agenda files, you’ll need to refresh those files after changes occur. Try this snippet to reload those files.

    (defun org-reload ()
      (interactive)
      (switch-to-buffer "mail.org")
      (revert-buffer nil 1)
      (org-agenda nil "a")
      (delete-other-windows))

]

Add-ons and other files

Related elisp code

Dragging URLs

This function uses org-mode support for plain list to facilitate dragging URLs from a webbrowser (or other apps) to an org-mode buffer:

(defadvice dnd-insert-text (around org-mouse-dnd-insert-text activate)
  (if (eq major-mode 'org-mode)
      (progn
	(cond
	 ;; if this is the end of the line then just insert text here
	 ((eolp)
	  (skip-chars-backward " \t")
	  (kill-region (point) (point-at-eol))
	  (unless (looking-back ":") (insert ":"))
	  (insert " "))

	 ;; if this is the beginning of the line then insert before
	 ((and (looking-at " \\|\t")
	       (save-excursion
		 (skip-chars-backward " \t") (bolp)))
	  (beginning-of-line)
	  (looking-at "[ \t]*")
	  (open-line 1)
	  (indent-to (- (match-end 0) (match-beginning 0)))
	  (insert "+ "))

	 ;; if this is a middle of the line, then insert after
	 (t
	  (end-of-line)
	  (newline t)
	  (indent-relative)
	  (insert "+ ")))
	(insert text)
	(beginning-of-line))
    ad-do-it))

Including all org files from a directory into the agenda

(setq org-agenda-files (file-expand-wildcards "~/org/*.org"))

Turn header lines into apparent visible separators

To make header lines more apparently visible in the buffer, set them a background color and change this part of ‘org-set-font-lock-defaults’, so that the header line is drawn across the screen:

	   ;; Headlines
	   '("^\\(\\**\\)\\(\\* \\)\\(.*\xa\\)" (1 (org-get-level-face 1))
	     (2 (org-get-level-face 2)) (3 (org-get-level-face 3)))

The only change is the `\xa’ character is added before the last closing paren.

Following Links

To follow links with RET, rather than a 2 key combo:

    (setq org-return-follows-link t)

You can also make TAB follow links in a similar way.

Opening pdf at specific page

To open links of type [~/test.pdf::3] i.e. open file at page 3:

    (delete '("\\.pdf\\'" . default) org-file-apps)
    (add-to-list 'org-file-apps '("\\.pdf::\\([0-9]+\\)\\'" . "evince \"%s\" -p %1"))

Opening pdf with alternative application

To open a link with a program other than the default(e.g. modify a pdf rather than read it):

(defun my-org-open-at-point()
  (interactive)
  (let ((org-file-apps '(("\\.pdf\\'" . "xournal %s"))))
    (org-open-at-point)
    ))

Editing Wikipedia

Org Mode can be easily configured to help edit Wikipedia articles by changing outline-regexp in the mode hook:

(add-hook 'org-mode-hook '(lambda () (setq outline-regexp "=+")))

If you use WThreeM, add the following instead:

(setq w3m-form-textarea-edit-mode 'org-mode)
(add-hook 'w3m-form-input-textarea-mode-hook
          '(lambda nil
                   (setq outline-regexp "=+")))

Discussion

Discussion should probably be moved to the Talk page

Org.el is now part of CVS Emacs. Great!

Google’s Code Hosting feature has a new wiki engine. Syntax is a simplified version of MoinMoin?. Here’s the neat bit: all changes are checked into the subversion repository in the wiki directory – each file has a *.wiki extension. Would it be possible to use org-mode to edit these? ‘Publish’ would be bound to ‘svn-checkin’ (or however that works). They support tags, too! Here’s the announcement: http://google-code-updates.blogspot.com/2006/12/happy-holidays-open-source-developers.html

The HTML exporter define anchor for section and subsection to navigate the document, is it possible to name the anchor like the section number it point to ?

If I have sections 1, 1.1, 1.2 and 2, the section 1.1 has an anchor called sec-2, section 2 has an anchor called 4, why not using sec-1.1, sec-1.2, sec-2 ?

Regards. – DanielDehennin

I use the Icalendar export capability to include my tasks to a shared webbased calendar.

I use mutli-state TODOs, I want them to appear in the ics file only for 1 state, example: #+SEQ_TODO: TO-PLAN WAITING CONFIRMED DONE

I output to the shared calendar only CONFIRMED tasks, others are for my personal organisation.

As I don’t want to export everything I modified ‘org-print-icalendar-entries’ to add a condition: only print entries which don’t match a regexp (only interesting part is past):

        (when (not (string-match my-org-ical-exclude hd))
          (princ (format "BEGIN:VEVENT
%s
%s
SUMMARY:%s
END:VEVENT\n"
                         (org-ical-ts-to-string ts "DTSTART")
                         (org-ical-ts-to-string ts2 "DTEND" inc)
                         hd)))

(setq my-org-ical-exclude "\\(TO-PLAN\\|WAITING\\|DONE\\)")

May be a better way to do this is to have special #+ICAL_EXCLUDE/#+ICAL_INCLUDE ?

Regards. – DanielDehennin

Are there any plans to integrate OrgMode with Oddmuse and OddmuseMode? I’m planning to start planning using OrgMode but since I collaborate with co-workers I need something bidirectional. The files in ~/org are not. But since I’m also evaluating OddmuseMode I thought a combination might be a very good idea. You immediately gain published plans. One would have to write a modul for Oddmuse, obviously, to understand the special markup. In this the user-defined keywords from OrgMode might be placed onto a specially named page.

Well, this is just brainstorming and since I didn’t actually use OrgMode for anything yet I might be talking rubbish. But it sounds good to me. --StefanKamphausen

For somebody like me, it would be far easier to add Org Mode’s markup rules to Oddmuse as a module. Then you could just use org-mode to write and oddmuse-mode to post. – AlexSchroeder

I envision a work-cycle like this:

  • M-x oddmuse-edit (Wiki, Page) (instead of find-file)
  • auto-mode-alist decides to put this in OrgMode
  • OrgMode-editing
  • M-x oddmuse-post (instead of save-buffer)
  • Then an oddmuse-org-mode-markup-Modul takes care of the rendering.

There are however some details, like the user-defined keywords in OrgMode and probably lots of other stuff that I don’t know about yet. Features like integration of OddMuse?’s blogging setup and calender-extension could be really neat. Ah, and HTML-checkboxes and JavaScript-Tree-Views and … oh sorry ;-) – StefanKamphausen

How does one implement this in Org? I have a library book that needs to be returned, but i don’t want it showing up in my things to do until 3 days before it is due. In HowmMode (which I currently use) I would simply set the a deadline with advance notice to 3 and I’m done. – PeterMielke

Is this what you want ?

    You can specify a different lead time for warnings for a specific
    deadlines using the following syntax.  Here is an example with a
    warning period of 5 days `DEADLINE: <2004-02-29 Sun -5d>'

YannHodique

Local TODO list?

I see org has a global todo list which shows todo items from every agenda files. Is there a todo list command which shows todo items only from the current file in the same agenda buffer format as the global todo list?

Yes. There are many ways to do this.

1. You can use “<” to restrict the TODO list to the current buffer or “<<” to restrict it to the current headline.

2. You can add a filetag at the top of the file and then filter the TODO list by tag using “/”.

3. You can write a custom agenda command that uses a different value for org-agenda-files. See http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php.

MattLundin

Thanks. It seems I have lot to learn about org-mode. :)

Before I saw your answer I came up with an other solution which fits my current approach, since at the moment I use files for context, so I always want buffer restricted todo lists:

(add-hook 'org-mode-hook 'my-org-mode-stuff)

(defun my-org-mode-stuff ()
  (local-set-key (kbd "<f12>")
                 (lambda (arg)
                   (interactive "P")
                   (let ((org-agenda-files (list (buffer-file-name))))
                       (org-todo-list arg))))
   ...
)

If I start to use more org features I may switch to one of the methods you listed. Thanks again.

After a good nights sleep using the info you gave me I came up with an other solution which is less hackish, since it uses the regular user interface and it pushes the necessary keys automatically to show a buffer restricted todo list:

(add-hook 'org-mode-hook 'my-org-mode-stuff)

(defun my-org-mode-stuff ()
  (local-set-key (kbd "<f12>")
                 (lambda ()
                   (interactive)
                   (push ?t unread-command-events)
                   (push ?< unread-command-events)
                   (call-interactively 'org-agenda)))
   ...
)

This is better than the previous one, because the agenda buffer shows the proper list even after a refresh. The previous solution showed the global todo list in that case.

I recently had to calculate the differences between log file timestamps. Eventually I figured out how to do this with emacs calc mode, and put the results together in org-mode spreadsheet tables. Here’s my writeup on emacs, calc, org-mode, and timestamps.

Phil Hollenback

Agree, org-mode “.org” export to MoinMoin? “.wiki” format would be fantastic. I don’t think the original request was made clearly enough, I am just reiterating that there is a need.

shouldDo.org is an Org-Mode “spreadsheet” to help you focus on your ShouldDOs, activities you should be doing to achieve results/outcomes/impact.

shouldDo.org tracks your weekly progress as a “score” (where perfect equals 100) as you perform these activities.

http://shouldDo.org


CategoryOutline CategoryPersonalInformationManager CategoryCalendar CategoryNeedsAttention