The ability to capture an idea really quickly is a very powerful feature of
org mode. Bind OrgCapture to a hotkey. (By default the neovintageous binding is shift+Z)
Once bound this allows you to make very quick captures of ideas as they come to you.
Right now, the capture mechanism ONLY supports capturing to a refile file. That is because, that is my primary way of using the feature. Capture into an inbox that I refile every day or so when I have a moment.
In the future I might support other mechanisms of capturing. Org has the ability to capture to a datetree for things like regular meetings, capturing to the active clocked item. Capturing to IDed or tagged items. Capturing to specific entries in specific files and a host of other options.
While I do have a very simplistic template mechanism, I decided after starting to implement that, that I would rather use a slightly beefed up version sublime snippets. I have left the template mechanism in the system but I will not be maintaining it going forward. Instead, use snippets!
A capture entry is specified something like so:
"captureTemplates":
[
{
"name": "Capture",
"type": "entry",
"snippet": "capture_heading",
"target": ["file","{refile}"],
},
]This states that when you run the Capture option, we will paste the capture_heading.sublime-snippet file into the capture buffer for your to edit.
I have extended the snippet environment to include additional variables and will continue to extend the list as there is need:
- ORG_INACTIVE_DATE
- An inactive date block at the current date
- ORG_ACTIVE_DATE
- An active date block at the current date
- ORG_DATE
- Just the current date
- ORG_TIME
- Just the current time.
- ORG_CLIPBOARD
- The current contents of the clipboard
- ORG_SELECTION
- The currently selected text in the current view.
- ORG_LINENUM
- The current line number in the current view
- ORG_FILENAME
- The filename of the current view
These can be used in your snippet to add a rich variety to your captures:
Here we will insert some properties with a link to your current location in the current view. The currently selected text inside a src block and the date you made this capture.
NOTE: In the following block, the github org parser gets confused with nested src blocks so I have formatted them funny so they will show up
<snippet>
<content><![CDATA[
* NOTE ${1:HEADING}
:PROPERTIES:
:FROM: [[file:${ORG_FILENAME}:${ORG_LINENUM}][Source]]
:CREATED: $ORG_INACTIVE_DATE
:END:
$0
# +begin_sr_c ${2:cpp}
$ORG_SELECTION
# +end_sr_c]]>
</content>
<tabTrigger>capture_heading</tabTrigger>
<scope>text.orgmode</scope>
<description>Capture Heading</description>
</snippet>By default org capture will open up a panel. When you close the panel by pressing escape the system will save your the capture automatically.
I have found the panel does odd things with neovintageous. I am still working to fix that. However:
Sometimes it is easier to work directly in the target capture file. Adding openas: direct to your capture config will flip open the file rather than using a capture panel.
"openas": "direct",Ultimately I would like to support the full gamut of OrgMode capture settings. At the moment I have a limited set, but I am working to expand it as I can make time. The following are supported:
- file
- specifies the file you wish to capture to
This will always insert at the end of the file.
"target": ["file","path to file"],
- file+headline
- unique headline in file
This will only insert under and exact match but anywhere in the hierarchy.
"target": ["file","path to file","Headline text"],
- file+olp
- full path to headline
This is like file+headline but specifies a full path to the node. Useful if there are multiple nodes
with the same heading.
"target": ["file","path to file","Headline1","Headline2","Headline3",...],
- file+regexp
- nodes text in the document is a match to the regexp
this will insert at the node who is situated at the first line in the file that matches a regexp
"target": ["file","path to file","REGEX"],
- file+olp+datetree
- This target creates a heading in a date tree for today’s date. The tree will be built under the outline path.
* 2021 ** 2021-03 March *** 2021-03-01 Wednesday - id
- A CUSTOM_ID property on a heading (I often use the TODAY property for this kind of targetting)
* Heading :PROPERTIES: :CUSTOM_ID: TODAY :END: - clock
- capture to the actively clocked target
Your type and target determine WHERE the snippet is inserted. Your snippet determines WHAT is inserted. Your snippet should reflect the type of insertion you are doing or you will get strange results.
{
"name": "Meeting",
// types:
// entry - An Org mode node, with a headline. Will be filed as the child of the target entry or as a top-level entry
// item - A plain list item, placed in the first plain list at the target location
// checkitem - A checkbox item. This only differs from the plain list item by the default template
// table-line - A new line in the first table at the target location. Where exactly the line will be inserted depends on the properties :prepend and :table-line-pos (see below)
// plain - Text to be inserted as it is.
"type": "entry",
// targets:
// file - text appened at end of file.
// id - text appened to existing org id in db
// file+headline - unique headline in file
// file+olp - full path to headline
// file+regexp - heading is a match to the regexp
// file+datetree - This target creates a heading in a date tree for today’s date. If the optional outline path is given, the tree will be built under the node it is pointing to
// clock - insert under current item being clocked.
// function <name>- generic function to find location for you
"target": ["file","{refile}"],
"snippet": "meeting_heading",
// DEPRECATED: "template": "* MEETING $0\n :PROPERTIES:\n:CREATED: [{datetime}]\n:END:\n "
// prepend - Normally new captured information will be appended at the target location (last child, last table line, last list item, …). Setting this property changes that.
// immediate-finish - When set, do not offer to edit the information, just file it away immediately. This makes sense if the template only needs information that can be added automatically.
// empty-lines - Set this to the number of lines to insert before and after the new item. Default 0, and the only other common value is 1.
// clock-in - Start the clock in this item.
// clock-keep - Keep the clock running when filing the captured entry.
// clock-resume - If starting the capture interrupted a clock, restart that clock when finished with the capture. Note that clock-keep has precedence over clock-resume. When setting both to non-nil, the current clock will run and the previous one will not be resumed.
// time-prompt - Prompt for a date/time to be used for date/week trees and when filling the template. Without this property, capture uses the current date and time. Even if this property has not been set, you can force the same behavior by calling org-capture with a C-1 prefix argument.
// tree-type - When week, make a week tree instead of the month tree, i.e., place the headings for each day under a heading with the current ISO week.
// unnarrowed - Do not narrow the target buffer, simply show the full buffer. Default is to narrow it so that you only see the new material.
// table-line-pos - Specification of the location in the table where the new line should be inserted. It should be a string like ‘II-3’ meaning that the new line should become the third line before the second horizontal separator line.
// kill-buffer - If the target file was not yet visited when capture was invoked, kill the buffer again after capture is completed.
// no-save - Do not save the target file after finishing the capture.
"properties":
[
],
} NOTE that properties are not currently supported at all and I only support the entry type. In the future I would like to extend this, but only as I have need or others in the community request it.
While the bulk of the capture contents is specified by the snippet used the target and type determine how the snippet gets inserted. Target chooses what file and Org Mode heading to insert under. Type determines where to insert under that heading. The following types are supported:
- entry
- An Org mode node, with a headline. Will be filed as the child of the target entry or as a top-level entry
- item
- A plain list item, placed in the first plain list at the target location
- checkitem
- A checkbox item. This only differs from the plain list item by the default template
- table-line
- A new line in the first table at the target location. Where exactly the line will be inserted depends on the properties :prepend and :table-line-pos (see below)
- plain
- Text to be inserted as it is.
The vanilla type is the entry, this means you want to insert a child node at the specified location, but what if you want to insert content. Plain is the default here. The snippet will be expanded at the end of the node. Item and checkitem will expand at the end of the first list they find in the node. Table-line adds a row to a table.
I like to capture ideas, snippets and meeting notes to my refile file. That makes input quick and dirty when I am in the middle of something else.
However, once captured it is a pain to move that stuff around. Org has a
feature that lets you do that much easier. Refile. OrgRefile lets you
quickly move a heading from one location to another within your known
org files.
While projects are great, it is often useful to archive a project once completed. Org has a powerful toolset for archiving completed subtrees.
OrgArchiveSubtree will take the subtree and put it in another file as an archived entry.
As usual the org manual is the best source of truth about archiving: Archiving That said a quick primer:
You can either add TODO FILL IN FROM HERE
#+ARCHIVE: %s_done::