- If you would like to install from source there are a few instructions here: manual_install.org
Once installed you will need to configure the plugin. OrgMode is a vast array of tools. This plugin already has quite a few features and tries hard to maintain the spirit, if not the full implementation of OrgMode.
So you installed it… Now what? One of the first things you may notice is that there are a number of syntax entries.
Org files end in a .org file extension. The only real syntax you should worry about is the OrgExtended syntax. The other syntaxs are in lower case to indicate they are used by the system but you should not need to set a buffer to those syntax modes.
Org files end in a .org file extension. Name a file something.org and you should be off to the races.
To get started the only really important item is your orgDirs entry. OrgExtended maintains metadata about all known org files. When you open a file it is scanned and tags are processed. OrgExtended will also proactively scan your org files in the background and generate tag information about them so it can do things like
- Generate your agenda
- Jump to a header that has a custom id.
- Jump to a tag
- Let you select from a list of actively known tags
The orgDirs entry tells OrgExtended where to scan for org mode files for use in auto completion, the agenda and various other tools. This is an important setting to provide. Go to:
Preferences > Package Settings > OrgExtended > User Settings
OrgExtended should have copied over an example settings file into your Packages/User folder for you to edit.
{
// Where are your org files?
"orgDirs": [
"c:\\Users\\ian\\notes"
],
}Often it is helpful to exclude some subdirectories in your orgDirs. This can be done as follows:
"orgExcludeDirs": [
"c:\\Users\\ian\\notes\\old",
"c:\\Users\\ian\\notes\\caldav",
],Out of the box OrgExtended comes with 2 built in color schemes. One light and one dark. These are pretty crappy schemes that I hand authored. They have the full set of custom scopes that I am using to give us the org mode coloring.
OrgExtended or OrgExtended-Light
{
// The color scheme to use for the capture buffer
"color_scheme": "Packages/OrgExtended/OrgExtended.sublime-color-scheme",
//"color_scheme": "Packages/OrgExtended/OrgExtended-Light.sublime-color-scheme",
// Where are your org files?
"orgDirs": [
"c:\\Users\\ian\\notes"
],
}
If you use the OrgExtended color scheme, OrgExtended should look okay no matter what. That said, part of the joy of sublime is customizing the look of your editor.
Org Extended now has a custom color scheme generator. It is still in development and has some limitations, but it makes OrgExtended much more enjoyable to use your own color scheme if you can generate it.
OrgExtended has a custom color scheme generator. It will take your current color scheme and generate an OrgExtended compatible variant out of it. It tries to help with tweaking your color scheme by giving you some pointers in the generated file on how best to tweak.
NOTE: This ONLY works with *.sublime-color-scheme files not the older texmate compatible *.tmTheme files the generator will silently fail if your current color scheme is using a tmTheme file.
To use it you should:
- Close all org mode files.
- Open up some source file.
- Run the command Org Create Color Scheme From Active
When run from a normal NON org mode buffer will sample the currently active color scheme, create a new color scheme file in:
Packages/User/OrgColorSchems/<originalName>_Org.sublime-color-scheme
It will then add a couple of key scopes such as:
- orgmode.preamble
- which is used to make the leading stars invisible on a subheading
- orgmode.state.*
- These are used to give the core built in states some color
This also adds comment blocks in the color scheme file that tries to help new users understand what their options are for extending and tweaking the new color scheme.
- Note this is based off YOUR active color scheme, it may not look that good! I have found that it tends to do better with dark color schemes than light ones.
- NOTE: This also changes the active color scheme for all of orgagenda, orgdatepicker etc. if you wish to switch back to the default you will need to change your settings in those settings files.
- IF you have any orgmode files open you will likely get error popups as the command changes the active color scheme as
the files are being generated.
This is a bit of an experimental feature. I will continue to improve it as time permits. So far I am finding it pretty reasonable.
There are a bunch of customizable features. At this point you have enough to get started. Jump to Startup to continue learning about features. To get an idea of some of the other options:
Capturing is a staple of org mode. Being able to be in the middle of working on something, capture quickly and then flip back to what you were doing is fundamental to the mind like glass getting things done philosophy of many org mode “ers.”
OrgExtended uses sublime snippets to create quick capture templates. You define a snippet, link it to a capture entry and then as you are editing capture and exit.
Here I have defined a snippet called todo_heading, it’s bound to Todo and I can use it to quickly make todo item captures. For more information see: Capturing
// I use this symbol for {refile} symbol expansion below.
"refile": "D:\\Build\\notes\\refile.org",
// Org Capture templates $0 is where the cursor ends up.
"captureTemplates":
[
{
// Although not fully implemented
// This is what I am heading towards:
// - types
// - snippet insertion for the template
// - target selection methods
// - properties insertion.
// - better capture buffer (not a panel)
"name": "Todo",
// 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",
// A sublime snippet that should be used as the template for the capture buffer
// I am working on interesting variables for this.
"snippet": "todo_heading",
// ONLY FILE IS IMPLEMENTED AT THIS POINT!
// 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}"],
// NOT IMPLEMENTED:
// PROPERTIES!
// 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":
[
],
},
],When you have a todo list and you finish the work, what do you do? A very core feature of org is archiving projects that are finished.
Archiving is a very personal choice. By default OrgExtended will archive to a myfile.org_archive file under a Archive heading. You can customize this using the following option:
// Globally where should things be archived?
// So the following will expand to myfile.org_archive
// NOTE: org allows for datetree/ and a few other options
// we probably only support a subset of those
// properly
"archive": "%s_archive::* Archive",You can archive a subtree using the “Org Archive Subtree” command.
While sublime controls when to enable the mode for a particular file the background org file scanning can be controlled with the following option:
// The Org DB will not load a file without one of these file extensions.
// It assumes we are somehow erroneously trying to load something wrong.
// If you create your own #+ARCHIVE: entries make sure the extensions are in here.
"validOrgExtensions": [ ".org", ".org_archive"],Org has a STARTUP tag that can be placed in a file. You can control the default startup state in your config file like so:
// Startup is equivalent to #+STARTUP: showall in a file
// but has an effect on all org files. This controls what mode
// the org files show as globally. Valid values are:
// - showall - everything but drawers is shown
// - showeverything - even drawers are shown.
// - contents - like a table of contents, contents of headings is hidden but all headings shown
// - overview - only top level headings are shown.
// - noinlineimages - do not show images inline
// - inlineimages - show inline images in file
// #+STARTUP: inlineimages
// #+STARTUP: noinlineimages
"startup": ["showall", "noinlineimages"],Inline image visualization will search for images using the following option:
// When looking for images in org files, where might those images be located?
// The first path in this list is where generated images will be placed.
// If this list is empty a subdir of images under the first entry in orgDirs will be used.
"imageSearchPath": [],TODO: Get around to documenting this stuff.
// We follow the same sort of syntax as the normal orgmode for todos.
// Right now I don't support logging tags on these, but that will come.
// I don't have smart syntax highlighting on these. The grammar file gives
// me some basic highlighting.
"todoStates": ["TODO","NEXT", "BLOCKED","WAITING","|", "CANCELLED", "DONE","MEETING","PHONE","NOTE"],
"resolver.jira.url":"http://sandbox.onjira.com/browse/%s",
"resolver.jira.pattern":"^(jira|j):(?P<issue>.+)$",
//email
"resolver.email.url":"mailto:%s",
"resolver.email.pattern":"^(?P<type>email|mailto):(?P<email>[^/]+)(/(?P<subject>.+))?$",
//prompt
"resolver.prompt.pattern":"^(cmd:|prompt:)(?P<path>.+)$",
//file: Only these extensions will be opened in sublime when in a link others will be opened externally.
"resolver.local_file.force_into_sublime":"'*.txt', '*.org', '*.py', '*.rb', '*.html', '*.css', '*.js', '*.php', '*.c', '*.cpp', '*.h', '*.png', '*.jpg', '*.gif', '*.cs'",
//"resolver.local_file.pattern":"^(file:)?(?P<filepath>.+?)(?::(?P<row>\\d+)(?::(?P<col>\\d+))?)?$",
// For the plantuml source blocks, where is planuml found?
"plantuml": "D:\\Build\\.imacs\\plantuml.jar",
// What does the composite agenda view show?
// You can add your own views but that is done through code.
// Right now I ONLY have this one composite view.
"AgendaCustomView": ["Calendar", "Day", "Blocked Projects", "Next Tasks", "Loose Tasks"],
// This is the template used to notify outside of sublime on org notifications
"ExternalNotificationCommand": ["C:\\Windows\\SysWOW64\\WindowsPowerShell\\v1.0\\powershell.exe", "-ExecutionPolicy", "Unrestricted", ".\\balloontip.ps1", "\"{todo}\"" , "\"{time}\""]