Remember, it's all just text.
FoldingText does some neat things, but in the end you are just typing. If you know how to type, you already know most of what you need to effectively use FoldingText.
(Click "#" to expand headings)
From 2001 to 2007 I made a program called Mori. My goal was to create the perfect information manager. A place to record, process, and create ideas. It did everything that I thought I wanted…
It turns out I liked plain text better. It didn't do as much, but it is clean, simple, and direct. Just me and my ideas without a bunch of user interface widgets in the way.
This left me in an embarrassing situation. I worked all day in my fancy information manager, and kept all my notes in plain text files on my desktop. Eventually I sold Mori.
But text files aren’t perfect either. After a while they get messy and are hard to understand and navigate. I think being free to make a mess is important, but without a way to eventually create structure they break down.
So in 2007 I created TaskPaper. It gave me a simple syntax to divide my text files up into projects, tasks, and notes. And it allowed me to filter those files so I could find things. It still works today, but it's intended for todo lists. I wanted to try again and make a more flexible solution.
That's why I created FoldingText.
It takes what I've learned building TaskPaper and tries to keep the good stuff, fix the mistakes, and make it more flexible. It's my next stab at a "plain text productivity". I hope it's useful!
Thanks, Jesse Grosjean
FoldingText uses Markdown formatting to give structure to your text files. These sections describe Markdown and how to use FoldingText to author Markdown documents.
- To create a heading, type "#" followed by a space.
- To create a list item, type "-" followed by a space.
- To create a numbered list item, type "1." followed by a space.
- To format text italic, surround with _s (single underlines).
- To format text bold, surround with **s (double asterisks).
- To create a link surround the link text with []s immediately followed by the target URL surrounded with ()s.
Use the Format menu to quickly insert formatting for many common items. You can also use Format > Clear Formatting (Control-C) to remove formatting characters.
That should get you started. There are more formatting options in the Markdown universe if you need them. FoldingText supports live highlighting of Markdown, GitHub Flavored Markdown, CriticMarkup, and most of MultiMarkdown.
FoldingText hides some syntax characters after you typed them. For example the **s used to make text bold are hidden. The characters reappear when you move the text cursor into that word for editing. I like it because it makes my document easier to read. You can turn it off using View > Hide Syntax.
Generally FoldingText should work like any other text editor: You type, and what you've typed flows down the page. Here are a few tips beyond basic typing.
When you are editing a list and press Return, FoldingText will automatically insert the syntax needed for the next item. This works in both unordered and ordered lists. To escape this behavior use Option-Return.
FoldingText allows you to select your text as you would in any other text editor. In addition FoldingText allows you to select word, sentence, paragraph, and branch boundaries.
Try out:
- Edit > Select > Expand Selection (Option-Command-Up)
- Edit > Select > Contract Selection (Option-Command-Down)
You can also undo/redo selection actions:
- Edit > Select > Undo Selection (Control-Z)
- Edit > Select > Redo Selection (Control-Shift-Z)
To move items (paragraphs) around use:
- Organize > Move Left (Command-[)
- Organize > Move Right (Command-])
- Organize > Move Up (Option-Command-[)
- Organize > Move Down (Option-Command-[)
You don't need to have a text selection for these to work; they will work on all selected lines, or if you have no selection, then on the current line with the text cursor. If you move an item that is folded both the item and all folded away nodes are moved together.
You can also move branches:
- Organize > Move Branch Left (Control-Option-Left)
- Organize > Move Branch Right (Control-Option-Right)
- Organize > Move Branch Up (Control-Option-Up)
- Organize > Move Branch Down (Control-Option-Down)
The Move Branch commands operate on the underlying tree structure. So if you move a branch (say a heading) then all contents that it contains is also moved. Also when you move branches the movements are constrained to maintain a valid tree structure. So for example if you have moving a child item you can't move it up past it's parent. Instead you have to move it left, making it a sibling of its old parent, and then up.
Click your mouse in the text and the text cursor is positioned where you click.
But...
- If you click on a link the URL will open in a browser
- If you click on a headings leading '#' the heading will fold
To escape those interactions and just place the darn cursor hold down the Option key when clicking. Your cursor is placed where you clicked and no other action is taken.
FoldingText also supports multiple cursors. Hold down the Command key and click your mouse to add a new cursor. (Useful if you want to edit multiple lines of text in the same way). Click with your mouse (without holding down Command) to reset to a single cursor.
Set up text replacements in System Preferences > Keyboard > Text panel. On my system, there's a default "omw" replacement that expands to "On my way!".
To use text replacements in FoldingText type the shortcut, "omw" for example, and then press the Tab key. The "omw" text will be replaced with "On my way!" and you can keep typing with a little more energy left in your fingers.
Typewriter scrolling goes along with full screen mode (though you can use it in normal screen mode too). It keeps your cursor centered vertically on your screen instead of getting stuck down along the bottom edge.
"Folding" allows you to visually hide parts of your document. It's useful for getting an overview of your documents structure, or just to hide a section that you are done with. Folds only effect your document's presentation, they don't change what is saved.
-
To fold a heading click the leading "#".
-
To remove a heading fold click the leading "#" again or just click the "…" symbol with your mouse.
-
To fold using the keyboard use View > Fold (Command-/). That will allows you to fold other structures, such as lists, that don't have a clickable "#" handle.
-
Use View > Expand By Level and View > Collapse By Level to set folds are a certain level in the descendants of the selected items. These commands allow you to progressively see more or less detail. Try them out by first doing a "Select All" to set the folding level for your entire document.
When your document has folds you will see a "folds" triangle in the upper left corner of your document. Click it once to remove any automatic folds added by focusing (see next section). Click it again to remove manual folds added using the above methods.
You can also use View > Show All (Command-Shift-A) to quickly remove all folds.
"Focusing" is similar to folding in that it also allows you to visually hide parts of your document using folds. It's different because you specify what you want to see, and FoldingText automatically adds the needed folds to hide everything else.
-
Use View > Focus (Command-U) to focus on the current item where your cursor is. If the current item doesn't have any children then you will get focused on the parent of the current item.
-
Use View > Focus Heading (Option-Command-U) and choose a heading from that popup. Folds are added so that you only see that heading and it's content.
-
Use View > Focus Tag (Control-U) and choose a tag from that popup. Folds are added so that you only see those tagged items and the structure that contains them.
You can remove folds added by focusing the same way you can remove folds that you've added manually. Click on them and they will go away.
You can also use the "folds" triangle in the upper left corner of your document. The first click will remove all folds that were added by focusing. The second click will remove folds that you manually created yourself.
You can also use View > Show All (Command-Shift-A) to quickly remove all folds.
To learn more about how focusing works behind the scenes please read about "node paths" in later sections.
FoldingText's command mode allows you to perform commands by typing their names instead of selecting them with menu items. This approach is fast, without forcing you to remember a separate keyboard shortcut for each command.
- To open the command mode use the shortcut Command-'.
- To perform a command type the command's name and press Return.
- To exit without performing a command press Escape.
Many FoldingText plugins use command mode to expose their functionality.
In a "normal" word processor you share your document by sharing the file or printing it. You can do the same thing in FoldingText, but you have other options too.
The Markdown syntax that FoldingText uses is designed to be part of a larger publishing process. Here are some of the ways you can use and publish content that you create in FoldingText:
-
Many online publishing systems (like blogs, forums, etc) support Markdown formatting directly. Just copy and paste the text that you want from your FoldingText document and paste it in as Markdown. The publishing system will generate nice valid HTML that's posted to the web.
-
FoldingText allows you to "copy" your document text as HTML or RTF. See the menu item Edit > Copy for these options. The implementation runs the selected text through a standard Markdown to HTML converter and puts that result on the clipboard.
-
For more sophisticated export you can use the app Marked. generates a live HTML preview of your document with different theme options. It also allows you to print or save the preview as a HTML, PDF, or RTF file.
-
Pandoc is rather complex, but powerful, option that can be used to publish Markdown to a variety of formats. If your goal is to publish a book or technical paper take a look at Pandoc.
-
There are lots of other apps that work with Markdown documents. Search for "Markdown" in the Mac or iOS store and you'll find lots of other tools that can work with FoldingText documents.
By default FoldingText files use the 'ft' extension instead of one of the normal Markdown file extensions. The reason that it does this is because, as you'll see in next part, FoldingText documents can contain some additional formatting.
But it's important to remember that all FoldingText files, and Markdown files, are just plain text. You can open any of them in any text editor. And you can open any plain text file in FoldingText no matter what the file extension is.
I didn't start this project with the goal of building a Markdown editor. I like working in plain text and just wanted a better place to do that. My goal was plain text productivity!
I'll now describe how FoldingText extends Markdown to create a general tool for plain text productivity. Let me start with an example and then explain how it works:
Jesse's.todo
- Show an example @done
- Describe how modes work
- Describe tags and properties
Look! My todo list, with checkboxes, in the middle of my text editor. How is this possible? It's possible because of three things FoldingText adds to Markdown:
-
Modes. In the above example the ".todo" gives the text under it special "todo" powers. For example unordered lists are displayed with leading checkboxes. Delete the ".todo" and you'll see the powers go away.
-
Metadata. Modes often need to store extra information. For example "todo" mode needs to know if a task is done. FoldingText adds some common syntax, such as the above "@done" tag, to store this metadata.
-
Node Paths. Node paths allow you to focus your document in sophisticated ways. For example I could use a node path to focus my document so that it only shows todo items that have not been marked as "@done".
And that's FoldingText's vision for plain text productivity: Markdown for structure, standard syntax for metadata, modes for custom behavior, and node paths for focusing.
Note: In "FoldingText's Story" I said my goal was to move beyond TaskPaper's todo list. And I have just shown off a todo list... It's a nice example! The important distinction is that FoldingText's core knows nothing about todo mode, it's just one of many possible extensions.
Modes extend FoldingText to solve task-specific problems. For example see (Help > Todo Mode Guide) and (Help > Timer Mode Guide).
- To declare a mode type '.' followed by the mode name at the end of a line. If there's a matching mode installed the ".mode" will become syntax highlighted.
When you declare a mode the mode effects all following lines that are "under" the line where the mode is declared.
Modes are an extension mechanism for FoldingText. To see and learn about the modes installed in your version of FoldingText look in the Help menu for the mode-specific User's Guides. If you are a JavaScript programmer you can even created your own.
In FoldingText headings, lists, paragraphs–those are the "things". What you want to add extra information about one of those things you can use tag and property syntax. For example todo mode uses "@done" tags to record that a particular list item is done.
-
To create a tag type "@" followed by the tag name.
-
To assign a value to a tag add "(value)" immediately after the tag name. For example @due(2012-11-26)
-
To focus on a tag in your document, click on the tag name. Click the value to focus only nodes with that tag AND value.
Some words are reserved and cannot be used as tag names. These include: "id", "class", "type", "line", "mode", "modeContext", "level", "property", "name", and "value".
Properties are like tags, except they exist on their own line. For example the .timer mode (Help > Timer Mode Guide) uses the "start" property to record the timer's start date.
-
To create a property, type the property name (single word) followed by " : " (space, colon, space) on its own line.
-
To assign a value to a property, type the value after the " : " syntax.
Generally use tags instead of properties if the tag/value text isn't to long and distracting. If the tag/value does become long and distracting consider using a property instead.
Internally each different kind of line (headings, list items, etc) is represented by a "node". The term "node" is used to highlight the fact that we are dealing with a tree structure. So for instance all the paragraphs under a heading are stored as child nodes of that heading node.
Node paths are used to find matching nodes in your document. So for instance this node path returns all "@today" nodes in the top level "inbox" section in your document:
/inbox//@today
Node paths are used internally to focus your document. When you click on a tag a node path is created to focus on nodes with that tag and folds are added to fold away everything else.
Right now there is no user interface to edit and evaluate node paths. But you can use AppleScript or JavaScript to create and evaluate node paths.
Here's a full description of node path syntax.
FoldingText is a plain text productivity "platform". Extend it to do more: use themes to change how FoldingText looks, use scripts to automate FoldingText, and use plugins to add new behavior.
- Find existing extensions
- Help > Software Development Kit