User’s Guide

Welcome to the Oak Outliner user’s guide.

Oak does some pretty neat things, but in the end it’s just text. If you know how to type, you already know most of what you need to effectively use Oak. Don’t get intimidated and just use the features you need. If you are using a PC use your Control key instead of the Command key when performing the keyboard shortcuts described in this guide.

Getting Started

Open your outline and type something like this:

Use “Tab” to indent your text, organizing it like this:

Right-click your mouse on one of the “headings” and choose the “Fold” command from the popup menu. The text under the heading will be replaced with a “fold” like this:

Try some of the other commands in the popup menu. When you use the “move” commands the heading and text indented under it are all moved together.

Learn these commands first!

To make good use of Oak you’ll need to internalize how to fold and move headings:

  1. Fold. (Command-,) Fold the current heading, or unfold the current heading if it is already folded.

  2. Move. Move the current heading and all text that’s indented under it in one of four directions:

    • Move Left. (Command-L)
    • Move Right. (Command-R)
    • Move Up. (Command-U)
    • Move Down. (Command-D)

Once you’ve memorized these commands you can work with your ideas at the outline level, instead of just typing text on the screen.

Formatting your Outline

Oak has a plain text user interface. That means there’s no “hidden” part of your outline that tracks what commands have been applied. Everything in Oak is determined by your outline’s text content. Use the following Markdown inspired conventions to format your outline’s text:

  • Use tab indentation to create your outline structure. If you select multiple lines, then use “Tab”, they will all be indented at once. See the “Working with your Outline” section for more advanced outlining commands.

  • To create _italic_ text surround it with _’s or *’s. You can also use the (Command-I) keyboard shortcut to automatically add the _’s for you around the current selection.

  • To create **bold** text surround it with **’s or __’s. You can also use the (Command-B) keyboard shortcut to automatically add the **’s for you around the current selection.

  • To create URL and email links, just type the link or email text and Oak will create a clickable link. Oak also recognizes Markdown’s inline link syntax (Command-K) like this [link label](

The above plain text formats are great because they allow you to have formatted text and links all in a simple plain text file. But all those syntax characters, especially long links, can make your document look messy. Because of this Oak automatically hides those syntax characters when you’re text cursor moves out of that text. When you move it back in they will display again so that you can edit them as needed.

Here’s what it looks like. Each of the following two lines has the exact same text, but you only see the syntax characters and link URL on the second line because that’s where the text cursor is:

Oak also has special commands to select your document by language and outline structure. It sounds rather complicated, but it’s all bundled up in two easy-to-use commands:

  • Extend Selection (Option-Command-Up) Extend the current selection up one level.

  • Contract Selection (Option-Command-Down) Reverse the previous “Extend Selection” commands.

Organizing with your Outline

You know how to format your outline, and with some copying, pasting, and indenting you can (re)organize it however you like. But if you just copy, paste, and tab while using Oak then you’re missing out.

Use these “outline” commands to take the next step. They allow you to think about and work on your outline, instead of just the text that it’s composed of.

  • Move You can move the the current heading (where the text cursor is) in four directions possible directions. Anytime you use a “Move” command, all text indented under the current heading is moved too.

    • Move Left. (Command-L)

    • Move Right. (Command-R)

    • Move Up. (Command-U) A heading can’t move up past the heading that contains it. To move it up further you need to first move it left, out from under its parent, and then up.

    • Move Down. (Command-U) A heading can’t move down into the next heading. To move it down further you need to first move it left, out from under its parent, and then down.

  • Promote (Command-]) Removes the contents of the current heading, and reinsert it right after the heading, no longer indented under it. Use promote when you decide that a heading is no longer needed, but you still want to keep its subheadings. Promote the subheadings, then delete the unnecessary heading.

  • Demote (Command-[) The opposite of promote. It moves all headings right after the current one under the current heading. It’s a way to make a new category from a flat list of items.

  • Delete (Command-Delete) Deletes the current heading and all subheadings that are indented under it.

Use folding to hide parts of your Outline

Folding allows you to hide the details of your outline so that you can see the big picture.

All the folded text is visually replaced by a single fold widget with three dots ”…”. Folded text is still in your document, it’s just hidden. When you select a fold it’s the same as selecting that hidden text.

Oak shows your folds in two styles depending on what text is around them.

If the fold is on a line with other text, then the fold is drawn with a dark background, so that it will stand out like this:

If the fold is alone on a line, then the fold is drawn like folded paper:

In both cases the folds act the same, it’s only the visual style that’s different.

Anytime your outline contains folded text Oak will display an outline level fold indicator in the upper left corner like this:

Click this to remove all folds in your outline. The first click will remove “automatic” folds that were created when you “Focused In” or filtered by a @tag. “Manual” are removed next.

Use the “Fold” command to manually create folds:

  • Fold. (Command-,) Fold the current heading (hiding all the text indented under it), or unfold it if it’s already folded. You can also unfold by clicking the fold with your mouse.

    • Fold Subs (Option-Command-,) Fold/Unfold the current heading and all headings under it.

    • Fold Everything (Control-Option-Command-,) Fold/Unfold all headings in your outline.

Focus to hide everything but the the current heading

When you use the “Fold” command you are hidding away details so you can see the big picture. But folds can also be used to hide the big picture while you work on the details. This is what the the focus command is for.

Here’s our outline after focusing in on the easy part:

  • Use Focus from the popup menu, to focus on the current heading. Oak will automatically create folds that hide the rest of your outline text.

  • Click on the triangle outline fold indicator in the upper left corner of your outline to show you full outline again.

Use tags to organize across your Outline

Outlines are a hierarchical way to organize information. This is a great start, but sometimes it’s not enough. If you have information that cuts across your outline hierarchy then you need another way to organize things.

For example, lets say you have a big project that you’ve divided up into a hierarchy of tasks. That’s all very good so far, but then say you want plan your day and gather all tasks that you want to get done in a single place.

This is a problem. The tasks that you want to do are spread all throughout your outline and there’s no single place in the hierarchy to see them all. You could create a special “today” heading and move your tasks there, but then you’d lose the context of where the task came from.

This is where tags come in. Tags allow you to “tag” or “flag” items in your outline with a label. You can assign multiple tags to a single item, and you can click on a tag link to automatically fold your outline to show only the parts with that tag.

To solve our problem we can simply tag all the tasks that we want to do today with @today and then click on the @today tag. Problem solved, now you just need to DO the tasks.

  • To create a new tag type ”@” followed by the tag name. You can add as many tags as you want to a single line.

  • To show only the parts of your outline with a given tag, click on the tag’s name. Folds are added to your outline, hiding the parts that don’t have the tag.

Saving and exporting your work

Oak autosaves your outline in your browser’s local storage. To open a outline you must use the same browser and computer that you create it with. Just copy/paste your outline text if you want to save it somewhere else.