org-configs/org-customization-guide.org

   1 #+TITLE:     Org-Mode Beginners Customization Guide
   2 #+AUTHOR:    Carsten Dominik
   3 #+EMAIL:     carsten.dominik@gmail.com
   4 #+LANGUAGE:  en
   5 #+OPTIONS:   H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   6
   7
   8 * Introduction
   9   :PROPERTIES:
  10   :ID:       68EE02FB-4F09-4BDC-8577-AD4F60DE1B1B
  11   :END:
  12
  13 #+index: Customization!Introduction
  14
  15 Org-mode is a highly customizable package.  It currently contains close to
  16 400 customization variables that can be changed to tweak every detail, and
  17 more than 260 are known to be actually used out there.
  18
  19 However, as a beginner you do not care about this kind of flexibility.  On
  20 this page, we have a list of five settings that you might want to try first
  21 in order to personalize your system.
  22
  23 Once you are done with that, we also have a list of some 40 variables that
  24 are [[https://orgmode.org/worg/org-configs/org-customization-survey-2013.html][changed by many users]].
  25
  26 * The Basics
  27
  28 #+index: Customization!Basics
  29
  30 ** Minimal customization
  31
  32 #+index: Customization!Minimal
  33
  34 The minimal customization needed to use Org-mode is -- *Nothing at all!*
  35 \par Org-mode works out of the box, and besides the steps described in the
  36 manual to [[https://orgmode.org/manual/Activation.html#Activation][activate]] it, /nothing is needed at all/.  Just open a /.org/
  37 file, press =C-c [= to tell org that this is a file you want to use in your
  38 agenda, and start putting your life into plain text.
  39
  40 OK, for completeness, let's just repeat what is needed to activate
  41 Org-mode in files with /.org/ extension, and a few important key
  42 assignments.
  43
  44 #+begin_src emacs-lisp
  45   (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
  46   (global-set-key "\C-cl" 'org-store-link)
  47   (global-set-key "\C-ca" 'org-agenda)
  48   ;; (global-font-lock-mode 1)  Not needed in recent emacsen
  49 #+end_src
  50
  51 ** Five small steps toward a personalized system
  52
  53 *** One: More TODO keywords
  54
  55 #+index: Todo Keywords
  56
  57 Define the TODO states you find useful and single letters for fast
  58 selection.  Customize the variable =org-todo-keywords= or simply do this
  59 right in the file with[fn:1:press =C-c C-c= in the line after changing it]:
  60
  61 #+begin_src org
  62   ,#+TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d) CANCELED(c)
  63 #+end_src
  64
  65 *** Two: Which tags do you use most?
  66
  67 #+index: Tag
  68
  69 You can always add tags freely and by hand, but if you configure the
  70 most important ones along with fast-access keys, life will be better.
  71 Configure the variable =org-tags-alist= or simply do this right in the
  72 file with[fn:1]
  73
  74 #+begin_src org
  75 ,#+TAGS: home(h) work(w) @computer(c) @phone(p) errants(e)
  76 #+end_src
  77
  78 *** Three: Which files are relevant for the agenda?
  79
  80 #+index: Agenda
  81
  82 When Org compiles agenda views like the the agenda for the current
  83 week (=C-c a a=) or the global TODO list (=C-c a t=), it checks all
  84 files in the variable =org-agenda-files=.  Instead of setting this
  85 variable explicitly, it is much easier to just add and remove the
  86 current buffer with =C-c [= and =C-c ]=, respectively.
  87
  88 *** Four: Find what you need to see now
  89
  90 If you need to sharpen the predefined agenda commands, define your [[https://orgmode.org/manual/Custom-agenda-views.html#Custom-agenda-views][own]]
  91 Agenda commands, using the variable =org-agenda-custom-commands=.
  92 This is a pretty complex variable, but if you use the customize
  93 interface[fn:2: =M-x customize-variable RET
  94 org-agenda-custom-commands RET=], it is not too hard.  Everyone
  95 ends up customizing this one after getting comfortable with Org-mode.
  96 Do checkout [[https://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php][this tutorial]] on building your own custom agenda commands
  97 as well.
  98
  99 *** Five: Capture ideas with predefined templates
 100
 101 #+index: Capture
 102
 103 Use =org-capture= to quickly capture ideas, tasks, and notes.
 104 Populate[fn:3: M-x customize-variable RET org-capture-templates RET]
 105 the variable =org-capture-templates= with templates and target
 106 locations.
 107
 108 * Pretend to be a power-user
 109
 110 Here is a list of the variables most frequently changed by power
 111 users.  The variables mentioned above are repeated in this list.  Yes,
 112 some power users change 60 options or more, but these showed up most
 113 frequently in the [[https://orgmode.org/worg/org-configs/org-customization-survey-2013.html][customization survey]].
 114
 115 *** Basic setup
 116
 117 #+index: Directory
 118 #+index: Agenda!Files
 119 #+index: Startup
 120 #+index: Archive!Location
 121
 122 Here are a few things about basic setup that many people change.
 123
 124 - org-directory :: Where are my Org files typically located?  Org
 125      acutally uses this variable only under rare circumstances, like
 126      when filing remember notes in an interactive way and prompting
 127      you for an Org file to put the note into.
 128
 129
 130 - org-agenda-files :: Which [[https://orgmode.org/manual/Agenda-files.html#Agenda-files][files]] do I want to be checked for entries
 131      when compiling my agenda?  Many people do not customize this one,
 132      but just use =C-c [= and =C-c ]= to add or remove the current
 133      file, respectively.
 134
 135 - org-startup-folded :: When visiting an Org file, in what [[https://orgmode.org/manual/Visibility-cycling.html#Visibility-cycling][folding
 136      state]] do I first want to see it?  Many use =#+STARTUP= options to
 137      set this on a [[https://orgmode.org/manual/In_002dbuffer-settings.html#In_002dbuffer-settings][per-file basis]].
 138
 139 - org-archive-location :: When [[https://orgmode.org/manual/Archiving.html#Archiving][archiving]] an entry, where will it go?
 140
 141 *** Editing behavior and appearance
 142
 143 #+index: Appearance
 144 #+index: Follow links
 145 #+index: Completion
 146 #+index: Ido
 147 #+index: Levels
 148 #+index: Blank
 149
 150 Besides being an organizer, Org-mode is also a text mode for writing
 151 and taking notes.  The following variables that influence basic
 152 editing behavior and the appearance of the buffer are often
 153 customized:
 154
 155 - org-hide-leading-stars :: Make the outline more list-like be [[https://orgmode.org/manual/Clean-view.html#Clean-view][hiding]]
 156      all leading stars but one.
 157
 158 - org-odd-levels-only :: Should [[https://orgmode.org/manual/Clean-view.html#Clean-view][2 stars]] be added per level?  This
 159      makes the indentation more like in a book.
 160
 161 - org-special-ctrl-a/e :: Should =C-a= and =C-e= behave specially,
 162      considering the headline and not the leading stars, todo
 163      keywords, or the trailing tags?  About equal numbers of users set
 164      this to =t= or to =reversed=
 165
 166 - org-special-ctrl-k :: Should =C-k= behave [[https://orgmode.org/worg/org-faq.html#C-k-is-killing-subtrees][specially]] in headlines,
 167      considering tags and visibility state?
 168
 169 - org-completion-use-ido :: Should /ido.el/ be used for completion
 170      whenever it makes sense?
 171
 172 - org-return-follows-link :: Should pressing RET on a hyperlink [[https://orgmode.org/manual/Handling-links.html#Handling-links][follow]]
 173      the link?  People who are used to this from web browsers often
 174      make this choice.
 175
 176 - org-blank-before-new-entry :: Org-mode tries to be smart about
 177      inserting blank lines before [[https://orgmode.org/manual/Structure-editing.html#Structure-editing][new entries/items]], by looking at
 178      what is before the previous entry/item.  Customize this to
 179      out-smart it.
 180
 181 *** The TODO keywords
 182
 183 #+index: Todo Keywords
 184 #+index: Todo Keywords!Faces
 185 #+index: Todo Keywords!Dependencies
 186 #+index: Checkbox
 187
 188 - org-todo-keywords :: Which [[https://orgmode.org/manual/TODO-extensions.html#TODO-extensions][TODO keywords]] should be used?  Also you
 189      can define keys for [[https://orgmode.org/manual/Fast-access-to-TODO-states.html#Fast-access-to-TODO-states][fast access]] here.  Very many people use this,
 190      or define the keywords with a =#+TODO:= setting in the buffer.
 191
 192 - org-todo-keyword-faces :: Here you can define different faces for
 193      different TODO keywords.
 194
 195 - org-enforce-todo-dependencies :: Should unfinished children [[https://orgmode.org/manual/TODO-dependencies.html#TODO-dependencies][block]]
 196      state changes in the parent?
 197
 198 - org-enforce-todo-checkbox-dependencies :: Should unfinished
 199      checkboxes [[https://orgmode.org/manual/TODO-dependencies.html#TODO-dependencies][block]] state changes in the parent?
 200
 201 *** Tags
 202
 203 #+index: Tag
 204
 205 - org-tag-alist :: Which [[https://orgmode.org/manual/Tags.html#Tags][tags]] should be available?  Note that tags
 206      besides the configured ones can be used, but for the important
 207      ones you can define keys for [[https://orgmode.org/manual/Setting-tags.html#Setting-tags][fast access]] here.
 208
 209 - org-tags-column :: How should tags be aligned in the headline?
 210
 211 - org-fast-tag-selection-single-key :: Set this to make the tags
 212      interface even faster, if all you normally do is changing a single
 213      tag.
 214
 215 *** Progress logging
 216
 217 #+index: Progress!Logging
 218 #+index: Logging
 219
 220 - org-log-done :: Do you want to [[https://orgmode.org/manual/Progress-logging.html#Progress-logging][capture]] time stamps and/or notes when
 221      TODO state changes, in particular when a task is DONE?  A simple
 222      setting that many use is =(setq org-log-done 'time)=.
 223
 224 *** Capture and Refile
 225
 226 #+index: Capture
 227 #+index: Refile
 228
 229 - org-reverse-note-order :: When adding new entries (or tasks) to a
 230      list, do I want the entry to be first or last in the list?
 231
 232 =org-capture= is great for fast capture of ideas, notes, and tasks.  It
 233 is one of the primary capture methods in Org-mode.
 234
 235 - org-capture-templates :: Prepare [[https://orgmode.org/manual/Capture-templates.html#Capture-templates][templates]] for the typical notes and
 236      tasks you want to capture quickly.  I believe everyone using
 237      =org-capture= customizes this.
 238
 239 - org-default-notes-file :: If you do not set up templates with target
 240      files, at least tell Org where to put captured notes.
 241
 242 /Refiling/ means moving entries around, for example from a capturing
 243 location to the correct project.
 244
 245 - org-refile-targets :: What should be on the [[https://orgmode.org/manual/Refile-and-copy.html#Refile-and-copy][menu]] when you refile
 246      tasks with =C-c C-w=?
 247
 248 - org-refile-use-outline-path :: How would you like to select refile
 249      targets. Headline only, or the path along the outline hierarchy?
 250
 251 *** Agenda Views
 252
 253 #+index: Agenda!Views
 254
 255 - org-agenda-start-on-weekday :: Should the [[https://orgmode.org/manual/Weekly_002fdaily-agenda.html#Weekly_002fdaily-agenda][agenda]] start on Monday, or
 256      better today?
 257
 258 - org-agenda-ndays :: How many days should the default agenda show?
 259      Default is 7, a whole week.
 260
 261 - org-agenda-include-diary :: Should the agenda also show [[https://orgmode.org/manual/Weekly_002fdaily-agenda.html#Weekly_002fdaily-agenda][entries]] from
 262      the Emacs diary?
 263
 264 - org-agenda-custom-commands :: Define your [[https://orgmode.org/manual/Custom-agenda-views.html#Custom-agenda-views][own]] Agenda commands.
 265      Complex, advanced variable, but pretty much everyone ends up
 266      configuring it.  Use customize to configure it, this is the best
 267      and safest way.  Do checkout [[https://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php][this tutorial]] on building your own
 268      custom agenda commands as well.
 269
 270 - org-agenda-sorting-strategy :: How should things be [[https://orgmode.org/manual/Sorting-agenda-items.html#Sorting-agenda-items][sorted]] in the
 271      agenda display.  Even though I think the defaults are very usable,
 272      power users tend to tweak this.
 273
 274 - org-stuck-projects :: How to find projects that need [[https://orgmode.org/manual/Stuck-projects.html#Stuck-projects][attention]]?
 275
 276 To reduce clutter in the task list for today, many users like to
 277 remove tasks from the daily list right when they are done.  The
 278 following variables give detailed control to what kind of entries this
 279 should apply:
 280
 281 - org-agenda-skip-scheduled-if-done :: Scheduled entries.  Many users
 282      turn this on.
 283
 284 - org-agenda-skip-deadline-if-done  :: Deadlines.  Many users turn
 285      this on.
 286
 287 - org-agenda-skip-timestamp-if-done :: Entries with any timestamp,
 288      appointments just like scheduled and deadline entries.
 289      Relatively few users select this one.
 290
 291 People who use Org like a [[http://www.newartisans.com/2007/08/using-org-mode-as-a-day-planner.html][day planner]], who [[https://orgmode.org/manual/Deadlines-and-scheduling.html#Deadlines-and-scheduling][schedule]] all tasks to
 292 specific dates, often like to not have scheduled tasks listed in their
 293 global TODO list, because scheduling it already means to have taking
 294 care of it in a sense, and because they know they will run into these
 295 tasks in the agenda anyway.
 296
 297 - org-agenda-todo-ignore-deadlines :: Don't show deadline tasks in
 298      global TODO list.
 299
 300 - org-agenda-todo-ignore-with-date :: Don't show any tasks with a date
 301      in the global TODO list.
 302
 303 - org-agenda-todo-ignore-scheduled :: Don't show scheduled tasks
 304      in the global TODO list.
 305
 306 *** Export/Publishing setup
 307
 308 #+index: Export
 309 #+index: Publish!Setup
 310
 311 - org-export-with-LaTeX-fragments :: Should [[https://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments][LaTeX fragments]] be
 312      converted to inline images for HTML output?
 313
 314 - org-export-html-style :: Customize the default [[https://orgmode.org/manual/CSS-support.html#CSS-support][style]] for HTML
 315      export.
 316
 317 - org-publish-project-alist :: Set up projects that allow many files
 318      to be exported and [[https://orgmode.org/manual/Publishing.html#Publishing][published]] with a single command.
 319
 320 * Become a true power user
 321
 322 If you want to become a true power user, [[https://orgmode.org/list/FD50CA36-A385-4C80-8E86-E3BE9F352B0A@uva.nl][see]] for yourself what some users
 323 do.  The Emacs customization system[fn:5:=M-x org-customize RET=] organizes
 324 all variables into a structure that can be used to easily [[https://orgmode.org/worg/org-tutorials/org-customize.html][find the one
 325 particular option]] you might be looking for.  Also, the [[https://orgmode.org/manual/][Org-mode manual]] and
 326 the [[https://orgmode.org/worg/org-faq.html][FAQ]] mention many variables in the appropriate context.
 327