Birch 1.2.1 Dev Release


  • Added API for rendering item badges.
  • Added API for rendering syntax highlighted body text.
  • Added new allowed formatting elements in file format.
  • Added vertical alignment guides (hide with LESS/CSS)
  • Added Focus-in and Focus-out animations.
  • Added “Group Items” command.
  • Changed item mode selection to include item handle.
  • Changed create a new child when focus-in on an item with no children.
  • Changed runtime DOM structure, any custom styles likely need updating.
  • Changed API to use ‘get’ style accessors to better match DOM conventions.
  • Changed handle to Workflowy style. Its cleaner and I think might work better when using different icons to indicate different types.
  • Fixed bug in some cases of shifting items to the left.

This download includes:

  1. Open docs/index.html for installation instructions and API docs. I think must open in Chrome or links don’t work because files don’t have extensions :frowning:.

  2. The birch-outline-editor folder contains the Birch outliner package that needs to be installed into Atom as describe in the docs.

  3. The Birch.bml file contains background and basic instructions for using the outliner. Open it in Atom once you’ve installed the Birch package and it should open as an outline.


This release makes a bunch of changes to the runtime DOM that make things more flexible going forward. As part of those changes it introduces a “Badges” UI concept. Badges are a place to display and interact with item attributes.

I’ve created a few inprogress/nonfinal/maybe/removed examples to help you get the idea. These all could have been deployed as separate atom packages (they are created with public birch API), but I’ve embedded them for now since updating atom packages is a pain until they are published to the atom package repo. If you want to see the code for these badges look into birch-outline-editor/packages.

  1. Now (in item mode) if you press any of the 1-7 number keys the selected items will get a data-priority attribute set. There’s also a badge renderer for that attribute setup, so you should also see a small color badge applied to the end of the item.

  2. I’ve also added three “status” commands. (replacing the previous “done” command) In item mode “s a” to set item active, “s c” to set item complete, and “s w” to set item waiting. Also just Spacebar to toggle complete. These commands all set the data-status attribute, and again there’s a badge renderer setup for that attribute that will render a badge in those cases.

  3. There’s also a badge renderer setup for the data-tags attribute. That attribute should be set to a list of comma separated tag names, and you should see them rendered.

I haven’t had time to make any of the badges interactive yet, but that’s the idea going forward. For example clicking on a “tag” badge should filter the list by that tag. Or clicking on a “due data” badge should open a datetime widget allowing you to adjust the date, etc. They are intended to be mini UI’s for viewing and interacting with item attributes.

I haven’t had much chance to use Birch extensively, but from playing around with it, it seems very good already.

The vim-like use of two modes is very interesting. I wonder whether you might want to add more commands like j/k for selecting next/previous item.

Also, there seems to be a bug when using the “Hoist” command when in insert mode. The view is set correctly, but all Birch commands (except new outline) disappear from the Atom commands list.

Regarding the hoist UI, I think there should be an indication at the top of the view of the item that was hoisted, or even better, a “breadcrumb” of all ancestor items.

Keep up the good work!

Yeah, in the end I think so. Though right now I haven’t been thinking to deeply about how all the different command shortcuts work together. Eventually I’d like to create some sort of system with some logic and pattern to it. Then I’ll see exactly which VIM commands fit in.

Thanks, I can reproduce this and will try to get it fixed for next release.

Tried to install as per instructions (amp install and apm link) but got error. DO I need XCODE?

Atom Version: 0.187.0
System: Mac OS X 10.10.2
Thrown From: birch-markdown-master package, v0.0.0

Stack Trace

Failed to load the birch-markdown-master package

At Cannot find module 'to-markdown'

Error: Cannot find module 'to-markdown'
    at Module._resolveFilename (module.js:351:15)
    at Function.Module._resolveFilename (/Applications/
    at Function.Module._load (module.js:293:25)
    at Module.require (module.js:380:17)
    at require (module.js:399:17)
    at Object.<anonymous> (/Users/xxxxx/.atom/packages/birch-markdown-master/lib/
    at Object.<anonymous> (/Users/xxxxx/.atom/packages/birch-markdown-master/lib/
    at Module._compile (module.js:475:26)
    at Object.requireCoffeeScript (/Applications/
    at Module.load (module.js:370:32)



  "core": {
    "themes": [

Installed Packages

# User
birch-markdown-master, v0.0.0
birch-outline-editor, v1.2.1
color-picker, v1.4.4
unity-ui, v2.0.3

# Dev
No dev packages

I’ve fixed this for the next release. In the meantime, the problem was that the editor lost focus. So you can work around the problem by hitting “Tab” key to regain focus. The things should work normally.

I haven’t looked closely at this, but glancing at your installed packages list, I notice birch-markdown-master, v0.0.0

As things like node type names have changed in birch-outline-editor, I think you will probably need to check that you are installing from the current version of birch-markdown at

(At the time of writing, it’s "version": "1.1.1" )

I don’t think you need xcode, instead as @complexpoint says I think the problem is that you have an old version of birch-markdown installed. One thing you can do to get things working quickly I think is to just disable birch-markdown:

Atom > Preferences > Packages > Birch Markdown > Disable

Then View > Reload Atom and I think things should work. Then if you want to play with birch-markdown stuff again you’ll need to install the latest version then reenable the package.

I added this in the current release, though no breadcrumb. Any breadcrumb style that I tried dominated the focused content more then I wanted. I guess try this out and see how it works for you. Possibilities going forward:

  1. Maybe Command-Click on un-hoist arrow pops up containment list like in OS X Finder window?

  2. Maybe a more complete breadcrumb could display in the Atom status bar?

The Command-Click option seems like it could work quite well: simple on the surface, but with more power behind a modifier key. I have less of a sense of whether displaying breadcrumb info in the status bar would be helpful.