org-ecosystem

---

name: Org Ecosystem description: This skill should be used when the user asks to "write org", "org-mode", "org file", ".org file", "org syntax", "org document", "org babel", "org export", "org agenda", "org capture", "GTD", "literate programming", "org publishing", or "org-mode workflow". Provides comprehensive Org-mode patterns and best practices.

<org_syntax> Hierarchical outline structure with stars - Top-level heading ** Second-level heading *** Third-level heading

Copy<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>

Copy    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>

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

Copy  - 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>

Copy<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>

<decision_tree name="task_state_selection"> What is the current status of the task? TODO NEXT WAITING DONE CANCELLED </decision_tree> </gtd_workflow>

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

Copy    #+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>

<decision_tree name="results_type"> What kind of output do you need? :results value :results output :results table :results raw :results silent </decision_tree>

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

Copy    (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>

<decision_tree name="export_backend"> 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>

<best_practices> 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>

<anti_patterns> Putting everything in one org file Split by project, area, or topic; use org-agenda-files

<error_escalation> 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>

<related_skills> 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>