dim-an/Zorgmode

Orgmode for sublime

Zorgmode is an implementation of org mode for SublimeText 3.

This plugin was tested on Linux. I hope it would work on Windows and OSX machines without any modifications, but I never had a chance to test that.

Installation

# Go to Packages directory (you can find it using menu Preferences → Browse Packages).
cd /path/to/package/directory
git clone git@github.com:dim-an/Zorgmode.git

Screenshot

Short command overview

Command	Keys (Linux)	Context	Comment
zorg_cycle	tab	headline	cycles through visibility of the current tree
zorg_cycle_all	shift+tab	any	cycles through visibility of all trees
zorg_move_node_up	ctrl+shift+up	headline, list item	moves current section (or list item) up
zorg_move_node_down	ctrl+shift+down	headline, list item	moves current section (or list item) down
zorg_cut_node	ctrl+X	headline, list item	cut section or list item
zorg_copy_node	ctrl+C	headline, list item	copy section or list item
zorg_delete_node	ctrl+shit+K	headline, list item	delete section or list item
zorg_cycle_todo_state_forward	alt+shift+right	headline	Cycles forward project state between (TODO, DONE, <empty state>)
zorg_cycle_todo_state_backward	alt+shift+left	headline	Cycles backward project state between (TODO, DONE, <empty state>)
zorg_toggle_checkbox	alt+shift+left	checkbox list item	toggles checkbox between unchecked ([ ]) and checked([X]) states
zorg_follow_link	enter	link	follow link
zorg_archive	ctrl+shift+A	headline	move current section into archive

Org syntax crash course

org is a markup language similar to markdown or reStructuredText.

* Headlines (<- this is example of level 1 headline)
Line that starts with one or more stars is a headline.
** Example of level 2 headline
*** Example of level 3 headline
** Headline level 2 again

* Lists
org has various kinds of lists. You can use `-' `+' `*' to make an unordered list.
List items can span multiple lines.
 - item1
   continuation of item1 must be properly indented
 - item2
    and item2 has sublist:
    * child1
    * child2

Ordered lists can be created using numeral that is followed by either '.' or ')'.
 1. First item.
 2. Second item.

* Links
 - [[http://github.com/][GitHub]] <- this is a link
 - [[http://github.com/]] <- this is also a link
 - http://github.com/ <- this is yet another link

* Projects and checkbox item
Headline that starts with TODO / DONE is a project, like this
** TODO Explain projects and checkboxes
List item that starts with [ ] / [X] is a checkbox list item
 - [ ] unchecked list item
 - [X] checked list item

Features

Currently Zorgmode doesn’t provide all the features of emacs’ org mode but it’s quite usable.

Cycle of visibility of sections

When cursor is over headline zorg_cycle (Linux: Tab) folds/unfolds corresponding section.

zorg_cycle_all (Linux: Shift+Tab) cycles among document visibility modes:

overview

only top level headers are visible

contents

all headers are visible but content is hidden

show all

all the content is visible

Hyperlinks

You can insert links in your document. Link can be in one of two forms:

1. https://github.com/dim-an/Zorgmode
2. [[https://github.com/dim-an/Zorgmode]]
3. [[https://github.com/dim-an/Zorgmode][Zorgmode homepage]]

To follow a link you should place cursor over it use zorg_follow_link (Linux: Enter). There are multiple types of links some of them will be opened using external application and others will be opened inside SublimeText. For the latter ones you can use default SublimeText3 commands Jump Back / Jump Forward (from Goto menu) in order to get browser-like forward/backward navigation.

Link types

Zorgmode supports multiple types of links:

1. Web links [[http://github.com/]]. Zorgmode will open them in your default web browser.
2. File [[file:/etc/passwd]]. Zorgmode will open them using SublimeText.
3. Files or directories [[file+sys:/etc/]]. Zorgmode will open them using your system default application (e.g. file manager for directories or media player for videos).
4. Sections [[Short command overview]]. Zorgmode will set cursor to corresponding section.

Link abbreviations

You can create link abbreviation. To create global link abbreviation use zorg_link_abbrev_list setting, for example:

   "zorg_link_abbrev_list": [
      {
          // [[gh:torvalds/linux]] -> [[http://github.com/torvalds/linux]]
          "scheme": "gh-user:",
          "expansion": "https://github.com/%s"
      },
   ],

With such setting link [[gh-user:torvalds]] will be interpreted by Zorgmode as [[https://github.com/torvalds]].

You can also create per document link abbreviations. To do this you should insert special line in any place of your document

#+LINK: gh-user https://github.com/%s

Structural editing

There are a number of commands that allow to swap, cut, copy or delete section or list entry. To use them cursor must be positioned on the headline of a section or on the first line of list item.

zorg_move_node_up (Linux: Ctrl+Shift+Up) and zorg_move_node_down (Linux: Ctrl+Shift+Down) swaps section (or list item) with its sibling. zorg_cut_node (Linux: Ctrl+x) cuts section (or list item). zorg_delete_node (Linux Ctrl+Shift+k) deletes (section or list item).

Projects and checkbox lists

Headlines that start with TODO or DONE keyword are projects.

* TODO Write Zorgmode documentation
** DONE Explain org syntax
** TODO Explain all the commands

Commands zorg_cycle_todo_state_forward (Linux: Alt+Shift+Right) and zorg_cycle_todo_state_backward (Linux: Alt+Shift+Left) cycle between project states (cursor must be over project headline):

• TODO
• DONE
• empty state (not a project)

Checkbox is a list item that starts with [ ] or [X].

- [ ] Unchecked item.
- [X] Checked item.

Command zorg_toggle_checkbox (Linux: Alt+Shift+Right) toggles checkbox item under cursor between checked and unchecked state. This command can also be used with selection to check (or uncheck) all checkboxes included in selected region.

Archive

Once you are done with your project you can move it to archive using zorg_move_to_archive (Linux: Ctrl+Shift+A). To set the archive file path insert control line

#+ARCHIVE: path/to/archive/file 

in any place of your document.

By default archive filename is current filename with _archive suffix appended to it.

Source code and examples

There are multiple ways to include example or source code in your .org document:

1. You can use #+BEGIN_EXAMPLE #+END_EXAMPLE markers:

   this is example inside org text:
   #+BEGIN_EXAMPLE
   text of example
   #+END_EXAMPLE
       

2. If example is small you can start example line with colon:

   This is example command:
   : git clone git@github.com/torvalds/linux
       

3. Finaly you can use #+BEGIN_SRC, #+END_SRC markers to include source code (and you can optionally specify what language is used):

   This is code block:
   #+BEGIN_SRC py
   def func():
     print("Hello world!\n")
   #+END_SRC
       

   List of supported languages includes: bash, c, c++/cpp/cxx, c#/cs, css, d, diff, erl, go, hs/haskell, java, js/JavaScript, lua, make, md/Markdown, ocaml, org, perl, php, py/python, r, rs, rst, rb, scala, sh, sql, tcl, xml, yml.

You can add spaces to indent your examples nicely:

* Some list item with example command
  : git clone git@github.com/torvalds/linux

Useful plugins

SublimeTableEditor plugin can help you edit tables in your org files.

Other implementations

There is another implementation of orgmode for SublimeText.