Org Ecosystem

Provide comprehensive patterns for Org-mode document creation, GTD workflow, literate programming with Babel, and export/publishing. Hierarchical outline structure with stars - Top-level heading ** Second-level heading \*** Third-level heading

<concept name="properties">
  <description>Key-value metadata attached to headings</description>
  <example>
    * Task
    :PROPERTIES:
    :CATEGORY: work
    :EFFORT:   2h
    :END:
  </example>
</concept>

<concept name="drawers">
  <description>Hidden content blocks</description>
  <example>
    :LOGBOOK:
    CLOCK: [2024-01-15 Mon 10:00]--[2024-01-15 Mon 12:00] =>  2:00
    :END:
  </example>
</concept>

<concept name="timestamps">
  <description>Date and time specifications</description>
  <example>
    <2024-01-15 Mon>           ; active timestamp
    [2024-01-15 Mon]           ; inactive timestamp
    <2024-01-15 Mon 10:00>     ; with time
    <2024-01-15 Mon +1w>       ; repeating weekly
    <2024-01-15 Mon .+1d>      ; restart from completion
  </example>
</concept>

<decision_tree name="timestamp_type_selection">
  <question>What is the purpose of this timestamp?</question>
  <branch condition="Schedule task, show in agenda">&lt;active timestamp&gt;</branch>
  <branch condition="Record date without agenda visibility">[inactive timestamp]</branch>
  <branch condition="Task repeats on fixed schedule">+1d/+1w/+1m repeater</branch>
  <branch condition="Task repeats from today when done">.+1d reset repeater</branch>
  <branch condition="Shift to future, catching up missed">++1d cumulative repeater</branch>
</decision_tree>

Ordered and unordered lists - Unordered item - Another item - Nested item

    1. First ordered item
    2. Second ordered item

    - [ ] Checkbox item
    - [x] Completed checkbox
  </example>
</pattern>

<pattern name="tables">
  <description>Spreadsheet-like tables with formulas</description>
  <example>
    | Name  | Quantity | Price |  Total |
    |-------+----------+-------+--------|
    | Item1 |        2 |  10.0 |   20.0 |
    | Item2 |        3 |  15.0 |   45.0 |
    |-------+----------+-------+--------|
    | Total |          |       |   65.0 |
    #+TBLFM: $4=$2*$3::@>$4=vsum(@2..@-1)
  </example>
  <note>C-c C-c to recalculate, C-c | to create table from region</note>
</pattern>

<pattern name="links">
  <description>Internal and external hyperlinks</description>
  <example>
    [[https://orgmode.org][Org website]]
    [[file:./other.org][Local file]]
    [[file:./image.png]]
    [[*Heading][Internal link]]
    [[id:unique-id][ID link]]
    &lt;&lt;target&gt;&gt; and [[target]]
  </example>
</pattern>

<decision_tree name="link_type_selection">
  <question>What are you linking to?</question>
  <branch condition="External URL">[[https://...][description]]</branch>
  <branch condition="Local file in project">[[file:./path][description]]</branch>
  <branch condition="Heading in same file">[[*Heading Name][description]]</branch>
  <branch condition="Stable cross-file reference">[[id:uuid][description]] with org-id</branch>
  <branch condition="Named target in document">&lt;&lt;target&gt;&gt; and [[target]]</branch>
</decision_tree>

<pattern name="blocks">
  <description>Special content blocks</description>
  <example>
    #+BEGIN_QUOTE
    Quoted text here.
    #+END_QUOTE

    #+BEGIN_EXAMPLE
    Verbatim text, no markup processing.
    #+END_EXAMPLE

    #+BEGIN_CENTER
    Centered text.
    #+END_CENTER

    #+BEGIN_VERSE
    Poetry or
    formatted text.
    #+END_VERSE
  </example>
</pattern>

<pattern name="markup">
  <description>Text formatting markup</description>
  <example>
    *bold*
    /italic/
    _underline_
    =verbatim=
    ~code~
    +strikethrough+
  </example>
</pattern>

<pattern name="footnotes">
  <description>Reference notes</description>
  <example>
    Text with footnote[fn:1].

    [fn:1] Footnote definition.

    Or inline[fn:: inline footnote definition].
  </example>
</pattern>

</org_syntax> Task state workflow configuration #+TODO: TODO(t) NEXT(n) WAITING(w@/!) | DONE(d!) CANCELLED(c@)

  - TODO Buy groceries
  - NEXT Write report
  - WAITING Review from team :@john:
  - DONE Complete project
  - CANCELLED Obsolete task
</example>
<note>@ prompts for note, ! records timestamp, | separates active from done states</note>

Quick capture templates (setq org-capture-templates '(("t" "Todo" entry (file+headline "~/org/inbox.org" "Tasks") "* TODO %?\n %i\n %a") ("n" "Note" entry (file "~/org/notes.org") "* %? :note:\n %U\n %i") ("j" "Journal" entry (file+datetree "~/org/journal.org") "* %?\n %U") ("m" "Meeting" entry (file+headline "~/org/work.org" "Meetings") "* MEETING %? :meeting:\n %T"))) %? cursor position, %i active region, %a annotation, %U inactive timestamp, %T active timestamp

<decision_tree name="capture_template_type">
  <question>What type of content are you capturing?</question>
  <branch condition="Action item or task">entry with TODO state to inbox</branch>
  <branch condition="Reference note or information">entry to notes file</branch>
  <branch condition="Daily journal or log">entry with file+datetree</branch>
  <branch condition="Meeting notes">entry with timestamp to meetings section</branch>
  <branch condition="Add item to existing list">item or checkitem type</branch>
</decision_tree>

<pattern name="agenda">
  <description>Agenda views and custom commands</description>
  <example>
    (setq org-agenda-files '("~/org/"))

    (setq org-agenda-custom-commands
    '(("d" "Dashboard"
    ((agenda "" ((org-agenda-span 7)))
    (todo "NEXT"
    ((org-agenda-overriding-header "Next Actions")))
    (todo "WAITING"
    ((org-agenda-overriding-header "Waiting For")))))
    ("w" "Weekly Review"
    ((agenda "" ((org-agenda-span 7)
    (org-agenda-start-on-weekday 1)))
    (stuck "")
    (todo "TODO")))))
  </example>
</pattern>

<pattern name="refile">
  <description>Task refiling configuration</description>
  <example>
    (setq org-refile-targets
    '((nil :maxlevel . 3)
    (org-agenda-files :maxlevel . 2)))

    (setq org-refile-use-outline-path 'file)
    (setq org-outline-path-complete-in-steps nil)
    (setq org-refile-allow-creating-parent-nodes 'confirm)
  </example>
  <note>C-c C-w to refile entry, C-u C-c C-w to jump to target</note>
</pattern>

<pattern name="clocking">
  <description>Time tracking with clock</description>
  <example>
    * Task with time tracking
    :LOGBOOK:
    CLOCK: [2024-01-15 Mon 10:00]--[2024-01-15 Mon 12:30] =>  2:30
    CLOCK: [2024-01-14 Sun 14:00]--[2024-01-14 Sun 15:00] =>  1:00
    :END:

    (setq org-clock-persist t)
    (setq org-clock-in-resume t)
    (setq org-clock-out-remove-zero-time-clocks t)
    (setq org-clock-report-include-clocking-task t)
  </example>
  <note>C-c C-x C-i clock in, C-c C-x C-o clock out, C-c C-x C-r insert clock report</note>
</pattern>

<pattern name="tags">
  <description>Tag-based organization</description>
  <example>
    #+TAGS: @home(h) @work(w) @phone(p) @computer(c)
    #+TAGS: urgent(u) important(i)

    - TODO Call dentist :@phone:urgent:

    (setq org-tag-alist
    '((:startgroup)
    ("@home" . ?h)
    ("@work" . ?w)
    (:endgroup)
    ("urgent" . ?u)
    ("important" . ?i)))
  </example>
</pattern>

<pattern name="archiving">
  <description>Archive completed tasks</description>
  <example>
    (setq org-archive-location "~/org/archive.org::datetree/")

    (setq org-archive-subtree-save-file-p t)
  </example>
  <note>C-c C-x C-a archive subtree, C-c C-x C-s archive sibling</note>
</pattern>

What is the current status of the task? TODO NEXT WAITING DONE CANCELLED </decision_tree> </gtd_workflow> Executable source code blocks #+NAME: example-block #+BEGIN_SRC python :results output :exports both print("Hello from Python") for i in range(3): print(f" Item {i}") #+END_SRC

  #+RESULTS: example-block
  : Hello from Python
  : Item 0
  : Item 1
  : Item 2
</example>

Common header arguments for code blocks #+BEGIN_SRC elisp :var x=5 :results value (* x x) #+END_SRC

    #+BEGIN_SRC shell :dir /tmp :results silent
    ls -la
    #+END_SRC

    #+BEGIN_SRC python :session py :results output

    # Persistent session across blocks

    import sys
    print(sys.version)
    #+END_SRC
  </example>
  <note>
    Header arguments:

    - :results (value, output, silent, replace, append)
    - :exports (code, results, both, none)
    - :var (variable binding)
    - :dir (working directory)
    - :session (persistent session)
    - :tangle (file to tangle to)
    - :noweb (noweb reference expansion)
  </note>
</pattern>

<pattern name="tangle">
  <description>Extract source code to files</description>
  <example>
    #+PROPERTY: header-args :tangle yes

    #+BEGIN_SRC python :tangle ./script.py :shebang "#!/usr/bin/env python3"
    def main():
    print("Generated from org file")

    if **name** == "**main**":
    main()
    #+END_SRC

    #+BEGIN_SRC nix :tangle ./default.nix :mkdirp yes
    { pkgs ? import &lt;nixpkgs&gt; {} }:
    pkgs.hello
    #+END_SRC
  </example>
  <note>C-c C-v t to tangle current file, :mkdirp yes to create directories</note>
</pattern>

<pattern name="noweb">
  <description>Literate programming with named blocks</description>
  <example>
    #+NAME: imports
    #+BEGIN_SRC python :noweb-ref imports
    import os
    import sys
    #+END_SRC

    #+NAME: main-function
    #+BEGIN_SRC python :noweb-ref main
    def main():
    print("Running main")
    #+END_SRC

    #+BEGIN_SRC python :tangle ./program.py :noweb yes
    &lt;&lt;imports&gt;&gt;

    &lt;&lt;main&gt;&gt;

    if **name** == "**main**":
    main()
    #+END_SRC
  </example>
</pattern>

<pattern name="results">
  <description>Result handling options</description>
  <example>
    #+BEGIN_SRC elisp :results value
    (+ 1 2 3)
    #+END_SRC

    #+RESULTS:
    : 6

    #+BEGIN_SRC python :results output
    print("line 1")
    print("line 2")
    #+END_SRC

    #+RESULTS:
    : line 1
    : line 2

    #+BEGIN_SRC elisp :results table
    '(("Name" "Age") ("Alice" 30) ("Bob" 25))
    #+END_SRC

    #+RESULTS:
    | Name | Age |
    | Alice | 30 |
    | Bob | 25 |
  </example>
</pattern>

<pattern name="language_specific">
  <description>Language-specific configurations</description>
  <example>
    (org-babel-do-load-languages
    'org-babel-load-languages
    '((emacs-lisp . t)
    (python . t)
    (shell . t)
    (js . t)
    (sql . t)
    (plantuml . t)))

    (setq org-confirm-babel-evaluate nil)
    (setq org-src-preserve-indentation t)
    (setq org-src-tab-acts-natively t)
    (setq org-edit-src-content-indentation 0)
  </example>
</pattern>

<pattern name="inline_code">
  <description>Inline source code evaluation</description>
  <example>
    The result is src_python{return 2 + 2} {{{results(=4=)}}}.

    Today is src_elisp{(format-time-string "%Y-%m-%d")}.
  </example>
</pattern>

What kind of output do you need? :results value :results output :results table :results raw :results silent </decision_tree> Document export fundamentals #+TITLE: Document Title #+AUTHOR: Author Name #+DATE: 2024-01-15 #+OPTIONS: toc:2 num:t author:t

  #+SETUPFILE: ./theme.setup
</example>

HTML export configuration #+OPTIONS: html-postamble:nil html-preamble:nil #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css"/> #+HTML_HEAD_EXTRA: <script src="script.js"></script>

    (setq org-html-validation-link nil)
    (setq org-html-head-include-scripts nil)
    (setq org-html-head-include-default-style nil)
    (setq org-html-doctype "html5")
    (setq org-html-html5-fancy t)
  </example>
  <note>C-c C-e h h to export to HTML file</note>
</pattern>

<pattern name="latex_export">
  <description>LaTeX/PDF export configuration</description>
  <example>
    #+LATEX_CLASS: article
    #+LATEX_CLASS_OPTIONS: [a4paper,11pt]
    #+LATEX_HEADER: \usepackage{geometry}
    #+LATEX_HEADER: \geometry{margin=1in}

    (setq org-latex-pdf-process
    '("latexmk -pdf -shell-escape %f"))

    (add-to-list 'org-latex-classes
    '("report"
    "\\documentclass{report}"
    ("\\chapter{%s}" . "\\chapter*{%s}")
    ("\\section{%s}" . "\\section*{%s}")))
  </example>
  <note>C-c C-e l p to export to PDF via LaTeX</note>
</pattern>

<pattern name="beamer">
  <description>Presentation slides with Beamer</description>
  <example>
    #+TITLE: Presentation Title
    #+AUTHOR: Presenter
    #+OPTIONS: H:2 toc:nil
    #+BEAMER_THEME: Madrid
    #+BEAMER_COLOR_THEME: default

    - Introduction
    \*\* First Slide

    * Point one
    * Point two

    \*\* Second Slide
    #+ATTR_BEAMER: :overlay &lt;+->

    - Appears first
    - Appears second
    - Appears third

    * Conclusion
    \*\* Summary
    Key takeaways here.
  </example>
  <note>H:2 means level-2 headings become frames</note>
</pattern>

<pattern name="markdown_export">
  <description>Markdown export for GitHub/GitLab</description>
  <example>
    #+OPTIONS: toc:nil

    (require 'ox-md)
    (require 'ox-gfm) ; GitHub Flavored Markdown
  </example>
  <note>C-c C-e m m to export to Markdown</note>
</pattern>

<pattern name="publishing">
  <description>Multi-file publishing projects</description>
  <example>
    (setq org-publish-project-alist
    '(("org-notes"
    :base-directory "~/org/notes/"
    :base-extension "org"
    :publishing-directory "~/public_html/"
    :recursive t
    :publishing-function org-html-publish-to-html
    :headline-levels 4
    :auto-preamble t)
    ("org-static"
    :base-directory "~/org/notes/"
    :base-extension "css\\|js\\|png\\|jpg\\|gif"
    :publishing-directory "~/public_html/"
    :recursive t
    :publishing-function org-publish-attachment)
    ("org" :components ("org-notes" "org-static"))))
  </example>
  <note>C-c C-e P p to publish project</note>
</pattern>

<pattern name="selective_export">
  <description>Control what gets exported</description>
  <example>
    * Exported heading

    - Not exported :noexport:

    #+BEGIN_COMMENT
    This entire block is not exported.
    #+END_COMMENT

    Text for export only. @@html:&lt;br&gt;@@ continues.

    #+BEGIN_EXPORT html
    &lt;div class="custom"&gt;Raw HTML here&lt;/div&gt;
    #+END_EXPORT
  </example>
</pattern>

What is the target format? HTML (ox-html) PDF via LaTeX (ox-latex) Beamer (ox-beamer) Markdown (ox-md, ox-gfm) ODT (ox-odt) </decision_tree> Quick capture notes and tasks Capturing ideas without interrupting current work</use_case> Unified view of scheduled items and TODOs Daily/weekly planning and review</use_case> Move entries to different locations Organizing captured items into proper locations</use_case> Execute code blocks in documents Literate programming, reproducible research</use_case> Export to various formats Publishing documents, creating presentations</use_case> Time tracking within org files Project time tracking, productivity analysis</use_case> Use one file per major project or area of responsibility Keep inbox.org for quick captures, refile regularly Use consistent TODO state workflow across all files Add SCHEDULED or DEADLINE to time-sensitive tasks Use tags for context (@home, @work, @phone) not categories Archive completed subtrees periodically Use org-id for stable cross-file links Set :EFFORT: property for time estimation Use column view for project overviews Configure org-agenda-custom-commands for common views </best_practices> Putting everything in one org file Split by project, area, or topic; use org-agenda-files Excessive heading depth (beyond 4-5 levels) Refactor into separate files or flatten structure Never refiling captured items Regular inbox processing (daily or at least weekly) Capture templates with too many fields Capture quickly with minimal fields, refine later Code blocks that modify external state unexpectedly Use :results silent for side-effect blocks, document clearly Absolute paths in org files Use relative paths or org-directory variable </anti_patterns> Understand org document requirements 1. Identify document type: notes, project, literate program, publication 2. Determine required features: GTD, babel, export 3. Check existing org patterns in project Create or modify org document 1. Set up document header with appropriate options 2. Structure content with appropriate heading levels 3. Add metadata (properties, tags, timestamps) as needed 4. Configure babel blocks for executable content Verify org document correctness 1. Check syntax with org-lint 2. Test babel blocks execute correctly 3. Verify export produces expected output Use appropriate heading levels (do not skip levels) Close all drawers and blocks properly Use consistent timestamp format throughout document Add :PROPERTIES: drawer after heading, not before Use #+NAME: before code blocks that are referenced Set document-wide header-args with #+PROPERTY: Use :noexport: tag for internal notes Minor formatting inconsistency Fix and continue Babel block execution error Debug block, check language support Export failure or corrupted output Check document structure, present options to user Data loss from failed tangle or corrupted file Block operation, require explicit user acknowledgment </error_escalation> Emacs Lisp configuration for org-mode customization Symbol operations for navigating org structures Fetch latest org-mode documentation Documentation patterns applicable to org export </related_skills> Use consistent heading structure (do not skip levels) Close all blocks and drawers properly Use relative paths for portability Excessive nesting beyond 4-5 levels Side effects in babel blocks without clear documentation Hardcoded absolute paths in documents