I am really confused why org mode doesn't accept subfolders. Refiling captures into subfolders doesn't work (doesn't see any files in subfolders). Org agenda doesn't work (same as refiling). Why is it like that? How dumping everything in a single location does not lead to massive problems trying to find anything even with search tools. Why is it not documented anywhere?

Example: work notes and personal notes. Wouldn't it make sense to separate them into separate folders?

  • 2
    You can put org documents anywhere in your file system. Neither org-mode nor org-agenda mandate a flat file system structure. You might be confused by a configuration issue, but the limitation you perceive doesn't actually exist.
    – g-gundam
    Oct 15, 2022 at 18:16
  • Hmm... how would one then configure org-agenda to pick up those org files outside org-directory? Would you have to configure init.el (I'm on doom emacs, so that's config.el) for each .org file? That may get complex with many such directories getting moved or renamed. Oct 15, 2022 at 19:07
  • Well, yes - if you decide to use a complicated directory structure, then you will have to work a bit harder to tell the agenda what files should contribute to it. BTW, a good rule of thumb might be: if a file should contribute to the agenda, then it might be a good idea to keep its pathname constant. Othewrise, you'll be missing deadlines :-)
    – NickD
    Oct 15, 2022 at 19:11
  • I wish it wasn't the case, because my industry has always worked with complicated folder structures in multiple, often completely different projects. If that's the case org mode isn't going to work for me. Oct 15, 2022 at 19:25
  • 1
    I think you are confusing two separate things: how a project is organized and how the (small) subset of your Org mode files contributing to the agenda is organized. The two have nothing to do with each other. The answer below is excellent: it describes one way of organizing your agenda files (note that there are only a handful). For another way, see Bernt Hansen's Organize your life in plain text!. The Org mode wiki Worg describes some more.
    – NickD
    Oct 16, 2022 at 1:50

1 Answer 1



As stated in previous comments, the limitations you perceived about org-mode and org-agenda's path requirements don't actually exist. However, it's very common to have misconceptions about how org-agenda works. I had them too. I didn't really know how to approach org-agenda for a long time, so I'm going to try to distill my understanding of it at a high level to answer your broader questions.

Org Agenda Requires Design

Some assembly is required when you decide to get started with org-agenda. It's so open-ended that you have to actually DESIGN a system that will work for your needs. My favorite example, and one that I actually use every day, is Orgmode for GTD by Nicolas Petton. His org-agenda system uses 4 files:

  • inbox.org - This is where he's setup org-capture to create TODO items to be refiled into the following files.
  • tickler.org - This is for small tasks to be done in the near term future.
  • someday.org - This is for tasks that might be nice to do in the distant future.
  • gtd.org - This is for current projects.

The configuration for his system looks like this when you put it all together.

(defun c/org-agenda ()
  ;; GTD with org-agenda
  ;; https://emacs.cafe/emacs/orgmode/gtd/2017/06/30/orgmode-gtd.html
  (setq org-agenda-files '("~/Dropbox/org/inbox.org"
   '("t" "Todo [inbox]" entry
     (file+headline "~/Dropbox/org/inbox.org" "Tasks")
     "* TODO %i%?")
   '("T" "Tickler" entry
     (file+headline "~/Dropbox/org/tickler.org" "Tickler")
     "* %i%? \n %U")
  (setq org-refile-targets '(("~/Dropbox/org/gtd.org" :maxlevel . 2)
                             ("~/Dropbox/org/someday.org" :level . 1)
                             ("~/Dropbox/org/tickler.org" :maxlevel . 1)))
  (setq org-todo-keywords '((sequence "TODO(t)" "WAITING(w)" "|" "DONE(d)" "CANCELLED(c)")))
  ;; This is the only part of this setup I haven't used yet.
  ;; (setq org-agenda-custom-commands
  ;;       '(("o" "At the office" tags-todo "@office"
  ;;          ((org-agenda-overriding-header "Office")
  ;;           (org-agenda-skip-function #'my-org-agenda-skip-all-siblings-but-first)))))
  (setq org-agenda-start-with-follow-mode t))

Designing Your Own System

From the above example, I want you to pay attention to two variables: org-agenda-files and org-refile-targets. Figuring out what should go in these variables is the heart of the design work required to use org-agenda.


Where do tasks come from?

By being in org-agenda-files, an org document gets the ability to schedule itself in the org-agenda system. The example I gave you limits this to 3 files, but if your situation requires more, you can add them to the list. If doing that manually is too cumbersome, you may have to write a function to populate org-agenda-files. Although my example used a flat directory structure, it's absolutely not required. They can be anywhere in the file system.


Why do you want to move items from one org file to another?

The GTD system answered this question by using refiling to express immediacy of a TODO item. Tasks start in the inbox.org and they get moved to tickler.org if they can be done soon. They move to someday.org if it doesn't have to happen right away. If the task is part of an ongoing project, they go into gtd.org. Files belonging to org-refile-targets were given an implicit meaning.

In the example, the refile targets are all in the same directory, but they could be anywhere in the file system.

Your Task

Read the documentation for these two variables, and think about how you want to use them. This will help you come up with a design that will make org-agenda work for your unique circumstance.

  • C-h v org-agenda-files
  • C-h v org-refile-targets

Also, I encourage you to read through the blog post I linked earlier to the GTD system. I think it's a great example of a working, cohesive system. It may not be suitable for your circumstance, but I think you can learn a lot from his example.

  • 1
    Very good answer - thanks!
    – NickD
    Oct 16, 2022 at 1:51
  • 1
    I would like to emphasize that even in the most complicated systems I know, the number of Org mode files contributing to the agenda is very small. I have about twenty in mine, but that's because I haven't cleaned it up in years: I only use three or four. They are all in a single directory (~/lib/org for me), but they don't have to be, as the answer makes clear. And I have hundreds of Org mode files that do NOT contribute to the agenda. Some are documents to be exported as HTML or PDF, some are notes for particular projects, some are lists of useful stuff - and they are all over the place.
    – NickD
    Oct 16, 2022 at 2:06

Your Answer

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

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