Clearly

Introduction

Clearly is a programmable structured text editor implemented as a JavaScript library. If you ever hacked in JavaScript, you can go and fork its GitHub repository (yay - it's open-source!). Of course you don't need any programming experience to use it. This tutorial will explain you everything you need to know :)

First of all - storage. The documents are stored in your browsers local storage so you can close this page and come back later to see them again. If you sign in through the form an the bottom of the page all your documents will be additionally synced accross all your devices.

Second thing is - don't worry about saving the document. All of the changes you make are saved instantly after a key has been pressed. Whole document is stored in your browser, remember? If you want to make some major changes you can save your document in a backup ([Ctrl + s]) and compare two versions later ([Ctrl + r]) ... We'll get back to backups later on.

You can create as many documents as you want. All you need to do is to go to clearly.pl/<document name> and new document will be created. You can use any names you want (even prefixing document name with a path) but be careful with document names - if you loose them, the document might become inaccessible. Also even slight change in document name will result in loading a different document. Although it may not seem so, this can be useful - for example if you need a place to store some secrets…

Document in Clearly is structured - every block of text is wrapped inside a paragraph. The paragraphs are grouped inside sections. In fact this paragraph is placed inside a section. You will soon get hang of structure manipulation - it's a powerfull and convenient tool.

Navigation

The document is a tree (in a mathematical sense of course) of HTML elements - sections, headers, paragraphs and a few others. To make work easier one element is always active - it has brighter background and is slightly indented.

When you click on an element it gets activated. Watch out not to click it twice though - it would start edit mode (indicated by red glow around the element). You can leave edit mode with [Escape] or by clicking outside currently edited element.

You can use arrows to navigate ([←] [→] [↑] [↓]) between next/previous elements and to ascend/descent in their hierarchy. This way of navigating through text is called tree navigation. Try it now. This is main way of browsing big documents and you will very quickly start to use it intuitively.

If you know how to navigate inside the webpage as it was a tree try holding down [Ctrl] and press [↑]/[↓]. This way you navigate i a way very similar to tree navigation but you can walk across elements at different nesting levels. Just as if they were placed one after another. This is why it is called list navigation.

[Home] and [End] keys will move you to the first and last element in the current section. Holding down [Ctrl] will cause you to move to start and end of the document.

Structure Manipulation

Converions

Various element types (such as header or paragraph) have keys associated to them. When you press an element key, the active element is converted to that particular element.
• select this paragraph by clicking on it
• press one of the digit keys from [1] to [6].
This way you can create headers of different sizes.

Now turn a header back into a paragraph: press [p] while the header is selected.

Deletion, insertion & killring

Press [Delete] or [Backspace] with an element selected to remove it from the page. Elements removed this way are not lost - they are put into killring instead.

You can retrieve an element from killring and paste it after current element by pressing [Insert] or [Ctrl + Backspace]. Press [Shift + Insert] or [Ctrl + Shift + Backspace] to add it before active element.

Creating new elements

If you press [Ctrl + \] you will insert new horizontal rule after selected element. Hold Shift to add it before instead.

You can create all kinds of elements by pressing [Ctrl + element key]. By default creating new elements takes you to the edit mode but since horizontal rules can't be edited you are left at navigation mode.

Compressing elements

You can compress elements by pressing the [h] key. Pressing it again will uncompress the element back. It allows you to compact sections or paragraphs that are too long or are not important at the moment.

Section wrapping & unwrapping

Press [Ctrl + Shift + →] to wrap active element with a section.

Similarily [Ctrl + Shift + ←] will cause the element to unwrap parent section.

Bubbling

Holding down [Shift] while pressing [↑] and [↓] will cause current element to bubble. You can supply this command with [Ctrl] to bubble accross other element boundaries. Use bubbling to reorder large parts of your document - move paragraphs, lists & sections accross the document.

Math

You can write pretty math eqations easily. Easily assuming you know what LaTeX is. LaTeX formulas that you write between $ and $ will be converted into math symbols when you press [M] (this is navigation mode command).

Example (activate this paragraph and press [M]): $\frac{d}{dx}f(x)=\lim_{h\to 0}\frac{f(x+h)-f(x)}{h}$.

LaTeX math can be quite troublesome so you can alternatively use ASCIIMathML to decorate text with math. Key to mathematize contents of active node is still [M].

Another example (activate this paragraph and press [M]): `f(x)=sum_(n=0)^oo(f^((n))(a))/(n!)(x-a)^n` . ASCIIMath formulas should be surrounded with backticks (`) and separated from the rest of the text with spaces.

TODO Lists

Clearly allows you to store and manage multiple task lists by annotating elements with task states (todo, cancelled, done, etc.).

Press [Tab] to change task state of the active element.

You can press it a few times - it cycles all possible states.

[Shift + Tab] cycles todo states backwards.

Under the hood, todo state management is done by todo mode. A nice feature of this is that todo mode is active during navigation & editing so you can use [Tab] also while writing.

Backups & Restoring

Unfortunately, Clearly doesn't yet support undo mechanism for changes done in navigation mode (such as shuffling and removing elements). To stay safe you should use backups.

[Ctrl + s] creates new backup for current page. Backup is created as a new page with ~ (tilde) added to path (backup for clearly.pl/tutorial/ is saved at clearly.pl/tutorial/~).

[Ctrl + r] reverts to backup. This command swaps current document with a backup. If no backup is avaiable - the document is reverted to its original state (this way you can for example revert changes made in this tutorial). You can press [Ctrl + r] repeatedly to quickly toggle between backup/original and current version.

[Ctrl + Shift + r] removes backup and saved page. Reverts document to its original state. Dangerous.

Text Editing

Press [Enter] at any time to start editing active element. Edit mode is indicated by red glow around active element. While in edit mode, most of the keys that switch or swap elements is inactive - instead you can move caret and enter text.

After a while you might want to speed things up. You can make new elements by pressing [Ctrl + Enter]. This command chooses element type based on the currently active element. When it is section - it will create new paragraph inside. When in the list - new list item. New item also checks if previous one is marked with todo state and sets marks new one with "TODO".

To exit edit mode press [Escape] or click on another elment.

You can also create paragraph series by pressing [Enter] while in edit mode (non-breaking carret return can be achieved by [Ctrl + Enter]).

Empty paragraphs are automatically destroyed.

Various text formatting can be done by pressing [Ctrl + formatting key]. Complete list of formatting keys is included at the end of Keyboard Cheatsheet.

Keyboard Cheatsheet

Element Types

Edit mode

Advanced usage

Including arbitrary HTML code

While in navigation mode, you can press ['] to turn HTML contents of an active node into text form. This is safe operation that escapes any unsafe character combinations and lets you make changes in the HTML code of an element.

When your edits are done, you can convert contents back into HTML form by pressing [Shift + ']. This operation isn't as safe as the previous one - it will discard any child elements that are already realized in DOM. All contents will be replaced by parsed text representation.

You can use arbitrary html code to include more advanced elements such as: buttons from social sites, iframes, images. Even custom scripts are allowed inside.

Using JavaScript console

Clearly is tightly integrates with your browser so you can use your browser's built-in JavaScript console to interact with Clearly. All methods and properities of editor are copied into the window object so you can use eq. active to refer to currently active element.

You can even make Clearly run scripts written inside itself. Select paragraph below and press [Shift + ']:

<script>
for(var i = 0; i < 10; ++i) {
  smartNew();
  active.text( "Task " + (i+1) + " created" );
  todo.first();
}
</script>

Although these functions are intended for programmers writing plugins, they may become useful in automating some repetitive work.

Bugs, Questions & Suggestions

If you happen to find a bug or have an idea about making Clearly better, leave it here or use GitHub to fix & share it.