Documentation

writemonkey edited this page May 31, 2018 · 72 revisions

Writemonkey 3

This document is work in progress. Things may change! Last updated: May 29th 2018 (for WM 3.0.6 Beta - Donkey Kong)

Download Beta >>

Writemonkey

Writemonkey

Why Writemonkey 3

Writemonkey 3 is the new incarnation of the original Windows only application that has been around since 2006. 10 years old and still kicking. It is quite possible that WM was the first text editor for writers with full markdown support. It was also among first distraction free editors out there. Writemonkey 2 will still be available for download, but won't be developed any further.

WM3 is available for all three major OS platforms - Windows, OSX and Linux and this is something that couldn't be done with the old code base. Also, hi-res displays are becoming popular and WM2, without unreasonable makeover, just isn't ready for that.

Although different WM3 still serves the same purpose. It is:

  • simple yet powerful,
  • plain text only,
  • minimal interface,
  • distraction free,
  • keyboard friendly and
  • markdown enabled

text editor for writers. Although it has some organizational and publishing capabilities it's primary function is to provide simple, engaging, hopefully even lovable writing environment.

Features at a glance

Writemonkey

Current state & road map

At this stage Writemonkey 3 is totally usable but not quite complete yet. I (the author) am using WM3 exclusively for all my writings and I don't look back. But that's me - it's possible that you'll miss some WM2 feature or prefer the old implementation of something.

Some more or less important modules are missing at the moment (May 2018):

  • Some kind of cloud synchronization mechanism
  • Proper installation mechanism

All or at least some of these will be available for the first regular release. Feedback on how to go with those is highly appreciated!

Major goals for tests in May 2018:

  • Detect and kill bugs
  • Evaluate existing features
  • Find out which (currently missing) features are indispensable and which are not that important
  • Acquire general feedback about usability and look&feel of new incarnation

For bug reports, feature suggestions and general discussions, please use project's GitHub issues page:

https://github.com/writemonkey/wm3/issues

Also see:

https://github.com/writemonkey/wm3/wiki/Changelog

for latest features, improvements and fixes.

Setup / installation (for wm Beta 3.0.6)

Currently (v 3.0.6 / May 2018) there is no special installation procedure available. All you have to do is download a zip file for your OS and unzip it's content somewhere on your disk. Make sure that you put the files into the directory that has full read&write permissions for your user account. To run WM3:

  • on Windows run writemonkey3/nw.exe file
  • on OSX run writemonkey3/Writemonkey.app file
  • on Linux run writemonkey3/nw file

Icon files are included with installation but you must (on Windows) create a shortcut to nw.exe and then assign the included .ico file to it.

Final release will feature proper installer for each platform.

Installation on Apple OSX Sierra

(May 2018, beta 3.0.6)

Since wm3 beta still lacks proper installer, setup on OSX High Sierra (latest version of OS) can be tricky. There is a new security feature "Gatekeeper Path Randomization" that can prevent wm3 from running.

To deal with this problem, do the following:

  • Download and unzip the file on some other non Sierra computer, put unzipped files on an USB stick and transfer them to your Sierra machine.

OR

  • Unzip Writemonkey3-OSX-beta6-may2018 using some 3rd party archiving program (like WinZip for OSX). Do not unzip to download folder, use some other location.

OR

  • Run from the terminal: sudo xattr -r -d com.apple.quarantine [full path]/writemonkey.app

Upgrade from previous version (for wm Beta 3.0.6)

To upgrade from previous version (like from 3.0.5 to 3.0.6) replace all Writemonkey files and folders with new ones. Your documents are stored in different location so they are safe. But you must manually restore, from previously made backup, all new application files and changes that you made to the wm folder since you first installed wm - plugins, themes, dictionaries, settings ...

You can, alternatively, install new version into some other folder. That way both versions will work, but with the same database files unless you change the default location in settings file. Be careful with that!

Storage

Your documents are stored in database file in the default local application data directory.

  • Windows: c:\Users\[user]\AppData\Local\Writemonkey 3\writemonkey3_sheets
  • OSX: /Users/[user]/Library/Application Support/Writemonkey 3/writemonkey3_sheets
  • Linux: /var/local/Writemonkey 3/writemonkey3_sheets

Use Open Folder with Database file from Command palette to open folder containing database files.

There are 4 additional files at the same location:

  • writemonkey3_sheets_repository file containing repository data (database file)
  • writemonkey3_sheets_history file contains history (restore points) data (database file)
  • writemonkey3_sheets_projects file contains project data (database file)
  • writemonkey3_custom_dictionary file containing custom dictionary (plain text file)

You can optionally change storage location. Open settings file (see: Settings file chapter below), search for data_directory setting and provide absolute path (even on Windows systems, use forward slashes / in paths, not \!) to the desired folder. This can be, for example, used for storing data into Dropbox folder to automatically sync documents between multiple computers with WM3 installed. Dropbox uses "Delta Encoding technology" for syncing files, so only changes are sent via network, so this trick can be used even with large database files containing millions of words.

Database maintains itself, but you can also compact database files manually via Command palette / Application: Database: Compact (The database file may grow big, especially if you are working on very large documents.)

Select Backup Database from the Command palette to create a complete database backup. The default location is [home directory]/WRITEMONKEY3_BACKUP/ but you can change that in the settings file (backup_directory setting). You can also tell wm to backup automatically. Set this in the settings file (backup_database_automatically setting). The default value is 6 which means that wm will backup database every 6 hours when wm is minimized.

Working with text files

Writemonkey 3.0.6 (May 2018) has basic support for text files. Documents stored in database can additionally also be stored as regular text files.

Bind existing document to a text file

Right click existing document name in document pane and select Bind to file from a context menu. You'll be presented with a regular Save As dialog, where you can choose a target directory and a file name. (WM will suggest the file name based on current document name, but you can change it to anything you want.)

Alternatively, you can select Document: Bind to File from a command palette.

Writemonkey will create a new file and keep it's content in sync with a database document. If you later open that file with some other text editor and change it's content, Writemonkey will show an alert and ask you which version of the text you want to keep.

Documents with a file bound to them are marked with a link icon in front of the document name.

Choose Unbind file from a context menu if you want to unlink the file from a document. Note that unlinked file won't be deleted from a disk, but it's content will no longer be in sync with a wm document.

Open existing text file in Writemonkey

When you have an existing text file and you want to open it with Writemonkey, you can:

  • Drag the text file into Writemonkey text area (not the document list). New document will be created and dragged file will be bound to it. Or ...
  • right click existing document on a document list and select Open file. You'll be presented with a regular Open file dialog. Navigate to a folder and select a file. Or ...
  • select Document: Open file from a Command palette.

Text files can also be dragged into repository. New item with file's text is created but there is no link between the file and repository item.

File related settings

settings_main.json file contains the following file related options:

  • files_default_extension - select a default extension for newly created text files. Default is txt, but you can change that to md, mdown or anything you like.
  • files_force_CRLF_line_breaks_on_windows - if this is set to true and the OS is Windows, files will be saved with Windows line breaks i.e. CR + LF and will show correctly in Windows Notepad. This is not recommended though, as all modern text editors on Windows support CR only (Unix) line breaks. If you don't need Notepad (and you shouldn't), leave this option set to false.
  • files_allow_drop_types - contains a list of file types that can be dropped into Writemonkey. By default .txt and .md files are valid.

IMPORTANT: Writemonkey can currently only handle UTF-8 files. If you happen to have files saved with some other encoding, you are out of luck. Note that nowadays all text files should use UTF-8 encoding as this is the standard & best choice.

Auto save & document history

Auto save function is on by default and set to fire every 5 minutes. Change that in settings file (auto_save_interval property). Set it to 0 to disable auto save functionality. Auto save fires only if document has been changed since the last save.

Writemonkey can keep complete history of your documents (on by default). To see restore points for a given document, open it, then select Document: Show Restore Points (Saved History) from the command palette. You'll be presented with all available restore points for that document.

Document history is stored in writemonkey3_sheets_history file. See Storage section for more info on that.

Settings file

General settings are stored in plain text file settings_main.json (JSON format) in setting directory. It is recommended that you don't modify this file, but copy your changes in settings_main_user.json that resides in the same directory.

Example: If you want to change font for plain text printing, copy from settings_main.json:

"plain_text_print_font": "Courier New, monospace",
"plain_text_print_font_size": "1em",

and save changes in settings_main_user.json:

"plain_text_print_font": "Arial",
"plain_text_print_font_size": "0.8em",

Be careful when editing settings file - it must be a valid JSON file:

{
	"propertie1": "value",
	"propertie2": "value"
}

Each property (except last one) in the file must end with a coma.

Restart Writemonkey after you modified the settings file.

Markdown

Writemonkey 3 is fully markdown compliant. For now it supports GitHub flavor that features some additional goodies. Short guide is available here:

https://blog.ghost.org/markdown/ and here: https://guides.github.com/features/mastering-markdown/

There are two additional non-standard syntax rules you can use in WM3:

Comments - commenting as implemented in Writemonkey is a simple yet powerful concept known to all computer programmers. It is used for two main purposes: a) adding comments to code elements or b) for commenting out (disabling) certain parts of code with an option to easily enable them again later. Writing text is not that different process so I dare to argue that a writer should benefit too (from a and b). You can mark parts that need further attention or some other kind of "note-to-myself" comments. Or you can comment out some parts of text – if you are over your word count limit, but still want to keep deleted parts in your original text document, for example. Or you can comment out alternative sections of your story. You may want to use them later.

To comment out whole paragraph, prepend it with two forward slashes. For parts within paragraphs (inline comments), surround part of text with two slashes at both ends. You can also use Ctrl+R shortcut to toggle comment on / off (paragraph or selection).

Meta data - WM3 also supports document meta data, part of multimarkdown standard (See Document meta data).

Command palette

Command palette is substitution for classic drop down menus that WM3 lacks. It contains all commands and can be used with keyboard or mouse.

Open / Close Command palette with Ctrl+Shift+P / Ctrl+Space on Windows and Linux or Cmd+Shift+P / Ctrl+Space on Mac.

With mouse you can open it by right clicking the top most edge of application window.

For example, if you want to change the current UI theme, open Command palette and start typing the. Three letters are enough to get View: Set Themes and UI Filters as your first choice. Hit enter and you'll get a list of all available themes. Use up/down arrow keys to navigate to the item you want or, if the list is too long, start typing the name of the theme to filter the list. Again select with enter.

When in second level list, use ESC or left arrow key to go back to the first level.

After you select a command, the palette sometimes closes automatically but sometimes it stays opened. That depends on the context of the command - when choosing themes, for example, the palette stays opened so you can test multiple themes without reopening it.

Many Command palette items are also tied to keyboard shortcuts, so if you remember what the key combo is, you don't need to use it at all. Some commands don't have keyboard shortcuts - in that case Command palette is the only way to go. In any case, you'll be using Command palette a lot in WM3!

Font size and text area width

Fonts and font sizes are defined in a css files for each theme separately. WM3 comes with some bundled fonts - Liberation Mono, Vera Mono, Hack Mono and Courier Prime. These are all mono space fonts, similar but with subtle differences and especially suitable for screens. Of course you can use other installed or web fonts, you just need to adjust theme file in themes folder. (See Themes section)

Font zoom and text area width can be adjusted when wm is running.

  • To set font zoom factor: Hold Alt + scroll wheel or use Ctrl+6 / Ctrl+7
  • To set text area width: Hold Ctrl + scroll wheel or use Ctrl+4 / Ctrl+5

You can also hold both, Alt and Ctrl to adjust both settings at the same time.

If you are using touchpad on your laptop, pinching with two fingers (if supported) can also be used for setting font zoom factor and text area width.

Text zoom and text area width defaults

Use Ctrl+0 shortcut to reset font zoom and text area width to their default values.

Both values can be set for full screen mode and for window mode separately:

Go to full screen (ESC) and adjust font zoom and text area width to your liking as described above. Then open Command palette (Ctrl+Shift+P) and select Lock Current Zoom as default. Repeat that for window mode.

UI zoom

When using WM3 on big hi-res displays the UI elements might be too small. If that is the case, open command palette and find:

View: Set User Interface Zoom Value

and set zoom value. 120, for example, means that all UI elements will be scaled to 120%. Note that this setting will not affect default editor's text size.

Distraction free mode

Shift+ESC toggles between window mode and distraction free mode. In distraction free mode wm goes full screen, all panes are hidden and the font size and text area width are set to their default (predefined) values. Hit Shift+ESC again to exit distraction free mode - exit full screen, show panes and adjust font zoom and text area width accordingly.

Sentence/paragraph highlighting & inactive paragraphs fading

Select View: Focus: Toggle Fade Inactive Paragraphs from Command palette or hit Ctrl+F6 to fade all but current paragraph. Another goody for distraction free writing. To set how much inactive paragraphs are faded, open settings file and search for:

fade_inactive_paragraps_amount

Select View: Focus: Toggle Highlight Current Sentence from Command palette or hit Ctrl+F7 to highlight a sentence under the cursor. Nice feature to focus on a current sentence.

You can customize the looks of the current sentence in a theme file, search for:

$wm-active-sentence {
	...
}

You can also highlight current paragraph if you prefer so. Use View: Focus: Toggle Highlight Active Paragraph from the Command palette. Customize active paragraph look in a theme file. Search for:

$wm-active-line {
	...
}

Whitespaces

To keep your texts tidy and well formated, use F8 to toggle visibility of whitespace characters - line breaks, tabs and redundant spaces (2 or more). Also handy when pasting text from other sources like web sites and formatting is not exactly what you wanted.

Typewriter scrolling

Typewriter scrolling is an ergonomic feature that keeps cursor fixed at certain vertical position of the screen. With traditional scrolling your text scrolls from top to bottom until it reaches lower edge of the screen. Eventually you end up constantly looking down at the last line which is not most natural and neck friendly posture. Typewriter scrolling instead keeps your current writing line fixed, text always scrolls up so your eyes never have to stray too far from one spot.

You can adjust typewriter scrolling position to your liking:

Put the cursor to desired vertical position on the screen, open Command palette and select Lock Typewriter Scrolling at Cursor Position.

Toggle Typewriter scrolling on / off with Ctrl+Shift+T.

Info bar

Info bar is located at the bottom of the screen and shows document name, word / character count and current time.

You can set which count units to show in info bar in settings file. Find and modify infobar_show_stats item. You can choose:

  • characters without spaces
  • characters with spaces
  • words
  • paragraphs / lines
  • standard pages (pages are calculated for a standard page - 30 lines, 60 characters)
  • reading time (200 words per minute)

Having word count in info bar is mandatory! You can add other units, but don't remove words.

When text is selected the info bar shows stats for selected text only.

Session indicators

If you are already working on an existing document and you'd like to reset the word count for a new session, open Command palette and select Start New Session. To stop the session, select Stop Current Session.

Following info will show at the top right corner of the wm window:

  • Partial word count, always starting from 0
  • Simple timer to show you the duration of the session
  • Words-per-minute (WPM) indicator to show how productive day you have

Session indicators are document based - each document has it's own set of data, including timer.

If goal tag is set in meta data header, session count is also shown on the progress bar (bottom of the screen) as a proportion of the total count.

For now partial count can only be presented as words. You can't have chars or pages ...

Productivity booster: you can optionally enable visual inactivity signal - session line (right-top corner) will start blinking if you stop writing for a certain period of time. This feature is off by default, enable it in settings file, properties: session_inactivity_signal and session_inactivity_grace_seconds. (This feature was removed in 3.0.5 - replaced by Stamina bar plugin)

Themes & Filters

Writemonkey

Writemonkey 3 themes are stored in writemonkey/themes directory. Each theme is represented by a single .css file that contains definitions for colors, fonts, sizes, backgrounds etc.

To change default theme, open Command palette and select Set Themes and UI filters command. The list of available themes pops up.

Basic knowledge of style sheet language (CSS) is needed to edit existing or create new WM3 themes. See http://www.w3schools.com/css/ for some info on that.

Quick example:

You want to change background and text color in default theme. Open wm-default.css file in any text editor and find:

:root {
  --main-background-color: #000000;
  --main-text-color: #C0C0C0;
  ...

Provide new color values. Save theme and reload it via Command palette.

To change font find:

:root {
	--editor-font: 'Courier Prime';
...

at the beginning of the theme file and provide some other font family name. You can use any font installed on your computer or those provided with WM3.

To change line spacing find:

$wm-editor {
	line-height: 1.8em;
	...

and set the value to anything you like - 2em means double spaced for example.

To change background image find:

$wm-ui-general {
	background-image: url(themes/space.jpg);
	...

and point to the image file you saved in themes folder. Use hi-res images for best results.

WM3 3.0.6 beta (May 2018) features new improved themes - Default, Default dark, Fresh mint, Snow white, Blue, Grey, Beige, Pine, Old typewriter and Industrial black. WM3 also supports background images.

Filters

Filters affect everything in Writemonkey window. They work very similar as filters in Photoshop. Filter Inverse for example inverses brightness of all elements, so your existing light theme becomes dark and vice versa.

To apply a filter, open Command palette, find and select Set Themes and UI filters and select one from the list. Play around to see what you'll get by applying filters to different themes.

Filter schemes are defined in settings/settings_main.json file. Find ui_filter_schemes definition to adjust them.

More info on filters: http://www.w3schools.com/cssref/css3_pr_filter.as

Caution: On older systems extensive usage of filters may affect responsiveness and font rendering (no subpixel antialiasing). You can always disable all filters with Reset all Filters command.

Brightness & Sepia

Those two filters can be adjusted separately via keyboard shortcut and are great for on-the-fly adjusting your viewport for different lighting environments. When the sun is down you shouldn't be staring at the immensely bright (blue) computer screen, instead, your displays lighting should become warmer and softer (yellow), mimicking the lighting in your room.

Use Alt + Shift + S to rotate sepia filter and Alt + Shift + B to adjust brightness.

Export & templates

Exporting your documents to other formats is currently not part of wm's core features, but there is the Preview plugin that offers basic markdown previewing and exporting. Open Command palette and search for Export to see available options.

Export templates are available in templates directory as regular CSS files.

Javascript in export templates

Advanced users can add custom javascript code to each template. To do so, create a file with the same name as a template but with a .js extension. For example:

Gotham.css
Gotham.js

When Gotham.css is chosen as a template, Gotham.js is automatically included.

Template's Javascript won't work if you export to .doc editor. It'll only work in preview window or if you export to default browser.

At this time (May 2018) existing templates need a lot of refining. Please fell free to make modifications or create new ones. Best export templates will be bundled with WM3 regular release.

Library & Document pane

Library pane

Library pane allows you to switch between different views in the document pane:

All - shows all documents in the library (except deleted documents). Documents are sorted by last modification time in descending order - newer files first.

Today - shows recent documents that have been touched last 24 hours.

Files - shows documents that are bound to a file.

Favorites - shows files marked with the star.

Search - shows the last search hits (see: Searching library for documents)

Trash - Shows deleted files. To undelete a file just re-save it. Right click the Trash item and select Empty trash to permanently remove all deleted documents.

Projects

(new in version 3.0.6)

WM3 sports simple project system that allows long form texts (like novels) to be split into multiple documents.

Create new project by right clicking Projects in library pane. Enter project name and hit enter. Alternatively use command palette (Projects: Create New). You can rename or delete project by right clicking the project name in the library pane.

When you delete the project all it's documents remain in the library but are not bundled together any more - select All in the library pane to access files previously assigned to a project.

Create new project document simply by hitting CTRL/CMD+N (or by clicking the + icon above the document list) when project is active.

Add existing document to a project by dragging it from the document pane to a project in the library pane.

Reorder project documents by dragging them with the mouse. Reordering is only possible inside a project - you can't reorder in other views.

Check project's word count by clicking the word count in the info bar (bottom right).

Documents marked as "scrap" will show dimmed on the document list and will be, for example, excluded from a word count. To mark document as scrap: right click the document name and select Mark as scrap.

Combine project's documents by right clicking the project name and selecting Copy project as text. The combined text (minus scrap files) will be available in clipboard. Paste it anywhere you like.

Toggle document/project pane visibility by clicking left most edge of the window (the same goes for the right side module pane). Within that click arrow icon at the bottom of document pane to toggle project pane visibility.

Document pane

Document pane features chronologically ordered document list with last modified documents at the top of the list. Each document tile shows:

  • Document name
  • Relative time (last saved)
  • Word count
  • Tags & colors (if provided in meta data)
  • Little progress bar (if meta data contain goal element)
  • Number of open tasks (if document contains unchecked to-do items)

If you prefer simplified / compact document list, right click any document on the list and enable Show compact document list.

Document list can also be accessed via Command palette - use Ctrl+Shift+U shortcut.

It is possible to auto fade all visible panes (+ infobar) when you start writing and then show them again after X seconds of inactivity. Set this in settings file, search for:

ui_autofade_amount_panes
ui_autofade_amount_infobar
ui_autofadein_delay
ui_autofadeout_actions_before_trigger
ui_autofadeout_animation_time
ui_autofadein_animation_time

Searching the library

(new in version 3.0.6)

Since version 3.0.6 it is possible to perform a full-text search over all documents in the database using input field above the document list. Hit enter key to perform a search. Search features simple syntax with the following rules:

dog cat bird
will find documents that have all 3 words anywhere in the document (default relationship between search terms is boolean AND).

john #todo #red
will find documents that have "john" anywhere and also have both "todo" and "red" tags in the meta data portion of the document.

$fish barracuda
will find documents that have "fish" in the document name and "barracuda" anywhere. It will also find documents that have "fishing" (or "FISHING" - search is case insensitive) in the document name.

tomato_soup
will find documents that have the exact phrase "tomato soup" anywhere in the document, but won't find those that have words "tomato" and "soup" in different places.

_fish_
will find documents with the word "fish" anywhere, but not documents with "fishing" or "selfish".

or: #red #blue #green
explicitly tell WM to use OR relationship between the search tokens. Will find documents that have tags "red" OR "blue" OR "green". or: must always be the first thing in the query.

Advanced users can also use regular expressions in search queries, for example:

^john ADVANCED
will find documents that have at least one paragraph that starts with "john".

fish.{1,2}\s ADVANCED
will find documents that include words "fish" or "fisher" but not "fishing" since there are more than 2 letters after the "fish" part.

\s\d{6}\s ADVANCED

Match documents that have a number with exactly 6 digits anywhere in the text.

Currently WM3 does not support searching with NOT - you can't match documents that don't include something.

Click on the "Search" item in the Library pane performs last search. Right click shows a recent searches list. Right clicking the search field in the document pane will do the same.

Jumps

Access jumps pane by clicking the compass icon in document pane on the left side of the screen or access them via Command palette (CTRL+SHIFT+O). Jumps help you navigate longer, more structured documents. Click jump item to instantly show it's location in the document (you can also use keyboard up/down keys). Jumps currently show following items:

Headings All paragraphs marked with #, ## ... Headings are represented in a tree structure and are numbered. A birds eye view to your entire document.

Bookmarks All paragraphs that contain a bookmark previously added with Ctrl+F2. Bookmarks are represented with red bookmark icon.

Comments All paragraphs that start with two forward slashes (blue balloon icon) and paragraphs that contain an inline comment (purple balloon icon).

Deletes / strikes All paragraphs that contain deleted text (~~this is striked text~~). represented by red x icon.

Collapsed ranges Parts of text that are folded / collapsed are represented by black "shrink" icon. (see Folding).

Tasks Tasks / to-do items:

- [ ] to-do
- [x] done

are represented with orange note icon.

Images Jump list also shows locations of markdown image links. Images are represented with a small thumbnail.

Jump list can be filtered using filter field at the top. Nothing fancy, just single word filter queries.

Select Copy Table of Contents as Text from Command palette to get a TAB indented list of headings in a document. Paste it where you need it.

Jumps are not customizable at this point. In the future versions it will be possible to add custom jump masks.

Keyboard shortcuts

Keyboard shortcuts are not customizable at this point (May 2018).

Keyboard shortcuts below are valid for Windows and Linux users. Mac users should use Command key instead of Ctrl!

General shortcuts

  • F1 - Show keyboard shortcuts (will open this list in default browser)
  • ESC - Toggle full screen
  • Shift + ESC - Toggle distraction free mode
  • F9 - Toggle left and right panes on / off
  • F10 - Show and focus document list / toggle documents / jumps
  • Ctrl + Shift + P or Ctrl + Space - Open Command palette
  • Ctrl + Shift + R - Access repository items via Command palette
  • Ctrl + Shift + U - Access documents list via Command palette
  • Ctrl + Shift + O - Access jumps list via Command palette
  • Ctrl + Shift + I - Access projects list via Command palette
  • Ctrl + N - New document
  • Ctrl + S - Save Document
  • Ctrl + P - Print selection or document as plain text
  • F7 - Toggle spell checking on / off
  • F8 - Toggle show whitespace characters on / off
  • Ctrl + F6 - Toggle inactive paragraphs fading on / off
  • Ctrl + F7 - Toggle active sentence highlighting on / off
  • Ctrl+Shift+T - Toggle typewriter scrolling on / off
  • F12 - Show / Toggle / Hide right pane modules
  • Ctrl + Q - Quit / Close Writemonkey
  • Alt + Shift + S - Rotate sepia filter
  • Alt + Shift + B - Rotate brightness filter
  • TAB - Focus editor when not in focus
  • Ctrl + 0 - Reset zoom
  • Ctrl + Shift + E - Trigger expandable snippet
  • Ctrl + 6 - Decrease font zoom
  • Ctrl + 7 - Increase font zoom
  • Ctrl + 4 - Decrease text area width
  • Ctrl + 5 - Increase text area width

Mouse related:

  • Alt + scroll wheel - Set text area width
  • Ctrl + scroll wheel - Set text zoom factor
  • Ctrl + Alt + scroll wheel - Zoom in / out

Navigation

  • Ctrl + left / right - Jump word left, right
  • Ctrl + Shift + left / right - Moving around and selecting
  • Ctrl + K,C - Scroll to selection / cursor
  • F4 - Jump to the position of last change
  • Home/End - Jump to the left / right edge of the on-screen line
  • Alt + Left/Right - Jump to start / end line
  • Ctrl + Home/End (Win) - Jump to start / end document
  • Cmd + Up/Down (OSX) - Jump to start / end document

Selecting with mouse

  • Double click - Select word
  • Triple click - Select paragraph
  • Alt + drag - Column select / add cursor for each line
  • Ctrl + click - Add another cursor
  • Ctrl + drag - Add another selection

Folding

  • Ctrl + 9 - Toggle fold / unfold all headings (markdown)
  • Ctrl + 8 - Toggle fold / unfold current heading (markdown)
  • F5 - Toggle collapse range (paragraph or selection)
  • F6 - Toggle segment focus (paragraph or selection)

Editing

  • Ctrl + C - Copy line / selection
  • Ctrl + Shift + C - Copy All
  • Ctrl + X - Cut line / selection
  • Ctrl + V - Paste
  • Ctrl + Shift + V - Paste as collapsed region
  • Ctrl + A - Select all
  • Ctrl + D - Select next occurrence
  • Ctrl + Enter - Insert line after
  • Ctrl + Shift + Enter - Insert line before
  • Ctrl + Shift + ↑ - Move line up
  • Ctrl + Shift + ↓ - Move line down
  • Ctrl + L - Select line - Repeat to select next line
  • Ctrl + Shift + K - Delete Line
  • Ctrl + K,K - Delete from cursor to end of line
  • Ctrl + K,Backspace - Delete from cursor to start of line
  • Ctrl + Shift + D - Duplicate line / selection
  • Ctrl + J - Join line below to the end of the current line
  • Ctrl + Z - Undo
  • Ctrl + U - Soft undo
  • Ctrl + Y - Redo
  • Ctrl + K,U - To Uppercase
  • Ctrl + K,L - To Lowercase
  • Ctrl + R - Comment / uncomment line or selection
  • Ctrl + T - Strike / unstrike line or selection
  • Ctrl + B - Bold (markdown)
  • Ctrl + I - Italic (markdown)
  • Ctrl + O - Code (markdown)
  • Ctrl + backspace - Delete word left
  • Ctrl + delete - Delete word right

Find & Replace

  • Ctrl + F - Find
  • Ctrl + H - Find and replace
  • F3 - Find next
  • Ctrl + F3 - Find under
  • Shift + Ctrl + F3 - Find under previous
  • Alt + F3 - Quick find / select all
  • Ctrl + 1 - Quick mark all

Repository

  • Shift + Ctrl + M - Move paragraph / selection to repository
  • Shift + Ctrl + L - Copy paragraph / selection to repository

Bookmarks

  • Ctrl + F2 - New bookmark
  • F2 - Go to next bookmark
  • Shift + F2 - Go to previous bookmark
  • Shift + Ctrl + F2 - Clear all bookmarks

WM3 bookmarks are not part of document's text. They are saved as document's meta data.

Remove individual bookmarks by clicking on them.

Context menus

WM3's GUI lacks, with a few exceptions, buttons and always present menus but there are practical context menus assigned to many GUI elements. You can for example right click:

  • Writing area (anywhere) - main menu
  • Top edge of the window - open command palette
  • Document name in document pane - document menu
  • Project name - project menu
  • Trash - empty trash
  • Search field in document pane - last searches
  • Tile in repository - repository options
  • Preview window - preview and export options
  • Misspelled words - spelling options

Smart characters

If enabled (on by default) some characters that usually come in pairs, like brackets and quotes, will auto close.

Default pairs:

" "
' '
` `
* *
_ _
< >
( )
[ ]
{ }
/ /

Select a word and type ( - the selected word will be enclosed in brackets on both sides - (word).

To make a selection italic you can always press Ctrl+I but you can also simply select something and type * - you'll get enclosed *some selection*. Type * twice and you'll get bolded selection - **selection**.

Smart characters will expand automatically also after the first character is typed even without selection.

Disable or reconfigure smart characters in settings file - smart_characters setting. To disable, give it an empty string:

"smart_characters": ""

Multiple cursors and selections

WM3 supports both, multiple selections and multiple cursors. Hold Ctrl (Cmd on Mac) and start selecting different parts of text. For example: select multiple words and then hit Ctrl+B to bold all of them at once.

To get multiple cursors - do not select, but just click different parts of text while holding Ctrl or Cmd key.

Trick: You have 5 lines of text and you want to make a list from them i.e. adding - in front of each. Hold Alt key and start dragging the mouse just left of those lines. The mouse pointer should change to + sign. You'll get 5 cursors, one at the beginning of each line. Now type dash and space ... you have a nice bullet list.

Repository

Repository in WM3 is a mixture of old wm2 plain text repository and corkboard plugin. It is very versatile and can be used any way you want. There is no right or wrong way. Use it as a to-do list, for notes and comments, maybe for storing previous (backup) versions of main text or for storing parts that are not yet ready to go into the main document ...

Open repository by clicking right most edge of the application window, then select Repository by clicking little arrow at the top. Alternatively you can hit F12 to toggle between all registered panes (repository is one of them).

Repository items can also be accessed via Command palette - Use Ctrl+Shift+R shortcut or find Repository: Access from Palette List in regular Command palette.

Every document has it's own repository that can host any number of text snippets of any length.

Snippets created in a document that is part of a project will be available for all documents in that project.

Create new repository item

You can do that in many different ways:

From existing text in the document:

Select a block of text, right click it and choose Move to repository or Copy to repository. There are also shortcuts for that: Ctrl+Shift+M = move, Ctrl+Shift+L = copy. Mac users must use Cmd instead of Ctrl, like for everything else. If nothing is selected, those commands act on the current paragraph.

Text can be freely dragged from repository to main text and vice versa. Select block of text in the document and drag it into repository window. Hold Ctrl to copy on Windows and Linux or Alt on a Mac (default is always move). You can drop text on existing item or on empty space, it makes no difference, a new item will be created at the top of the list. When you drop snippet into the document it is shown as a placeholder for collapsed region (See Text folding). Click it to expand the text.

From other applications:

If you want to store text from other applications, the best way to go is via clipboard. Copy at source and use New from clipboard in repository (right click repository window). Alternatively you can also drag&drop selected text from other applications into repository.

Repository item types

Snippets of text

Repository can host text snippets of any length, it might be a short paragraph or a whole book. No limits here.

If snippet starts with #, the first paragraph is bolded. That way you can name your snippets if you want.

Comments

The only difference between normal text snippet and a comment is that the text, like in documents, starts with two forward slashes. In repository comments are represented with different background color (depends on the theme in use).

Links

Repository can also host links (URLs). When clicked, stored link opens in default browser.

To store a link, copy any URL to the clipboard, right click repository window and select New from clipboard. The link will be stored in markdown format:

[](https://en.wikipedia.org/wiki/Monkey)

If link name is provided later on:

[About monkeys](https://en.wikipedia.org/wiki/Monkey)

it is used as the caption for the link item. If not, part of actual URL is shown.

Images

Repository can also hold local or remote image links. To store image in repository copy it's link (not the actual image!), right click repository window and select New from clipboard. Writemonkey will recognize the image link and show it.

When added to repository the link is converted to markdown image link, so:

http://domain.com/image_name.jpg

becomes:

![](http://domain.com/image_name.jpg)

Like everything else in repository, you can drag image to the main text.

Links to local images must start with file://, for example:

file://c:/some_dir/photo.jpg

becomes:

![](file://c:/some_dir/photo.jpg)

Currently only images with extensions jpg, jpeg, gif or png are supported.

Macros

Macros are actually mini plugins that can reside in the repository. When clicked the content, that is actually a javascript code, is executed. Macro must start with:

/* Macro name */

and must be followed by a valid code. For example:

/* Google lookup */
var e = _editor;
var r = "https://www.google.com/?#q=";
if (e.somethingSelected()) {
	var q = e.getSelection();
} else {
	var w = e.findWordAt(e.getCursor());
	var q = e.getRange(w.from(), w.to());
}
q = q.replace(/ /g, "+").trim();
opener(r + q);

This macro, when clicked, fetches the word under the cursor (or selection) and shows Google search results in default browser. A lot like lookups in wm2.

You can easily adapt it for other sources, just replace the first line with some other URL mask:

var r = "https://en.wikipedia.org/w/index.php?search=";

There is no plugins API documentation at this point (May 2018) but it will be available later on)

Expandable snippets

Expandable snippets are just like replacements from Writemonkey 2. You can set trigger strings that will be replaced by predefined replacement text.

To set expandable snippet create new repository item and enter text:

{sig}John Doe
Some Street 4
City

The string between curly brackets (mandatory!) is the trigger and everything else is a replacement. All expandable snippets are marked with a little lightning strike icon on the right side of repository item tile.

To use this replacement, simply type sig and then hit Ctr+Shift+E. sig is replaced by your name and address.

If you use [date] placeholder in replacement part, it is replaced by an actual date&time. Change default format in settings file (expand_datetime_format). [clipboard] placeholder is replaced with current clipboard text.

Expandable snippets are global by default, i.e. they are active for all documents, not just for the document they were created in.

To see the list of all available expandable snippets, open repository context menu, select Show and then Expandable Snippets. Or simply type $ into repository filter field.

Available snippet actions

Reorder snippets

by dragging them with a mouse. Always drop one item on existing one.

Right click snippet

to get context menu for that item. The options are:

Mark with color - Choose one of predefined colors to mark the snippet. Assign meanings to colors however you like. If you don't like predefined colors, set your own in settings file by modifying repo_item_colors field.

Toggle strikethrough - You can use this to additionally mark the item. For example if snippet is a to-do item, mark it as done that way.

Make bigger. - Show more text in bigger tile. Double clicking the snippet has the same effect.

Scroll snippet - Click top / bottom of the snippet (only on big tiles) to scroll its content up or down.

Set as global - Global snippet is visible in every document, no matter where it was created. That way you can have links or macros always visible. You'll recognize global snippet by dark right edge. If you make global snippet local again it is linked to the current document and not the one that was created in.

Copy text - Put content of the snippet in clipboard. Content is always plain text.

Move to document - Move snippet to the document (at current cursor position). Actually it is much better to just drag it there.

Edit - Show complete snippet and make it editable. You can also Ctrl click it. When done editing, right click and choose Save&close. Or Ctrl click or hit Ctrl+Enter.

Delete - permanently remove snippet.

Repository filtering

By default you only see snippets that belong to the current document and global snippets. When using filter field at the top of the list, you are filtering all snippets in database, not just local ones.

Filtering by type

Open repository context menu and select Show. Sub menu with the following items pops up:

  • Default view (empty filter field)
  • All snippets (*)
  • Links & Macros (@)
  • Expandable Snippets ($)
  • Images (!)

Alternatively you can type special character into the repository filter field to get the same results. For example, use * to show all snippets in the database or $ to get a list of all expandable snippets in the database.

Repository filtering is very basic at this point, you can't use compound queries with operators etc., only simple single strings.

Text folding

Folding is all about temporarily hiding parts of text in your document. Hidden text remains part of the document i.e. it affects word count but it is neatly packed and out of your sight.

There are three kinds of folding in WM3: Header folding, Collapsed ranges and Segment focus.

Header folding

Markdown headers (paragraphs that start with #, ## ...) can be folded by clicking little arrow that appears next to them. That way you can hide the content of the whole section and only keep the header/title visible. Great for outlining and document structuring.

To fold or unfold header under the cursor use Toggle Fold/Unfold Heading from Command palette or via Ctrl+8.

You can also fold or unfold all headers in the document at once using Toggle Fold/Unfold All Headings or just by Ctrl+9.

Folded headers are persistent i.e. saved as document meta data.

Collapsed ranges

You can select a part of the text and use F5 to replace that part of text with a placeholder. That way you can temporarily hide text in a document. If nothing is selected F5 affects current paragraph. You can also collapse regions using context menu (right click) or with Command palette. You can unfold the placeholder by clicking on it or simply by hitting F5 again (toggling).

Collapsed ranges are persistent i.e. saved as document meta data.

You can see placeholder in action if you drag item from repository to the document.

You can use context menu command or Ctrl+Shift+V shortcut to paste clipboard text as a collapsed region.

Mouse over the word badge in placeholder will show you preview of the text contained in that collapsed region.

Segment focus

Segment focus hides everything but selected text. Use F6 to enter focus mode. If nothing is selected only current paragraph remains visible. Hit F6 again to exit focus mode. You can also click the 3 dots icon at the top of the wm window.

Segment focus is great if you want to give full attention to a single snippet of text and temporarily forget about everything else in your document. It's a great psychological trick you can do on yourself.

Segment focus is not persistent i.e. documents always open with segment focus off even if it was on when document (or application) was closed.

Document meta data

You can add meta data to every document. Meta data must be placed at the top of the document (literally the first line) and can span multiple lines. Wm recognises those lines and syntax highlights them according to the current theme. Each meta data field must have the following structure:

field_name: value

At the moment following field names are supported:

name: This is document name

If name field is present, it's value is used for the document name. If absent, first heading (#) is used. If there is no marked headings in the doc, the beginning of the first paragraph is be used.

tags: tag1 tag2 red blue

You can mark your document with any number of tags that can later be used to filter your document list. Tags can be any word you like, but if you use one of the standard color names, the tag is represented with a little color mark. See list of available colors: http://www.w3schools.com/colors/colors_names.asp.

goal: 10000

Use goal name to set the word count limit for that document. If this item is included, the progress bar becomes visible under the info bar.

due: Jul 20 2017

This sets the due date for the document. (Current status: due date is saved with your document, but it is not yet used anywhere at the moment.)

Search, replace

Searching and replacing in WM3 is simple and straightforward. To get a list all available commands and their shortcuts, filter for search in Command palette.

All search matches are highlighted and their positions marked on the scrollbar. To hide them just start another search and hit escape.

Using regular expressions

If you need to perform more complex searches, you can use regular expressions. Surround your search query with 2 forward slashes /regex_query/ Example:

/^Mary/

only finds Mary at the beginning of the paragraph.

Selection matches

One quick way to search for text is using Show Selection Matches command.

Select a block of text and hit Ctrl/Cmd+1. If nothing is selected, word under the cursor is used. All matches in a document are highlighted and their positions marked on the scrollbar. To hide matches hit Ctrl/Cmd+1 again.

Spell checker

Writemonkey 3 features simple spell checker based on Hunspell standard that is used by many big players like Open Office suite, Firefox, Google Chrome and others.

To set the dictionary open Command palette and select Select Spelling Dictionary. You'll be presented with a list of available dictionaries. Choose one.

You can use F7 or Toggle Spelling on/off via Command palette to enable / disable spelling. When enabled misspelled words appear underlined with a red line (depends on the chosen theme). If right clicked, the list of spelling suggestions pops up.

You'll also be presented with 2 other options:

  • Ignore spelling - misspelled word are ignored for all documents as long as wm is opened

  • Learn spelling- the same as Ignore, but misspelled word is stored in custom dictionary file and will persist when wm is reopened. Custom dictionary file (writemonkey3_custom_dictionary) is stored in the same folder as database files. There is only one custom dictionary and it is universal for all languages.

Adding dictionaries

Writemonkey 3 comes with English dictionary (en_US) preinstalled. To add dictionary for your language, do the following:

  • Download additional dictionary packs via https://github.com/wooorm/dictionaries and unzip the file.
  • Find the files for your language. You need 2 files for each language - .dic and .aff. For German language for example, you'll need both de_DE.dic and de_DE.aff files.
  • Put those files into lang directory that resides in the main WM3 folder.
  • That's it, you can now select the language as described above.

FOR VERSION 3.0.6 - Currently there are problems with some Romance languages (Portuguese, Italian, Spanish ...). They won't work properly or can even crash Writemonkey due to huge memory leak. Sorry for that!

Sounds

There are 2 kind of sounds in WM3 - white noise sounds and typing sounds (as a plugin).

To play white noise sound, open Command palette and select Start/Stop White noise Loops. You'll get the list of available sounds. Select one to start it. Choose Stop all sounds to disable.

Use white noise sounds for loud environments and focused writing. Like white light, the conglomerate of all light frequencies, white noise is something we hear when there is a lot of background noise of various sources. Sound of the river, wind in the trees, sound of heavy rain ... The positive effects of those sounds on writing process can be two fold: a) they are very comforting and even have kind of hypnotic effect, b) they mask out all other sounds, especially spoken words, even when played in a very low volume. Imagine: you are writing in a café with your laptop and you don't want to be disturbed by conversations around you. Pop up the ear pieces, enable white sound feature and you are in the zone again :)

There are also good old typing sounds available as the Click Clack plugin (see Plugins). To enable scheme, open Command palette and select Enable/Disable Typing Sounds. Then select the scheme from the list. Disable with Disable Typing Sounds.

Plugins

WM3 plugins are premium feature only available to donors (the same as with wm2). Please donate via PayPal, and you'll get a key that unlocks plugin functionality. (See License).

There is no plugin API documentation at this point (May 2018).

If you are a developer and you'd like to create a plugin for Writemonkey 3, please write to master at pomarancha dot com for guidance.

WM2 plugins are not compatible with WM3!

Preview plugin

Preview plugin (if installed) shows HTML version of current markdown document. Use F12 repeatedly until preview is visible in the module pane (right side of the wm window).

Use context menu (right click anywhere on the preview pane) to see preview options. You can select templates, print, open in browser or default installed .doc editor (Word, Open Office ...).

You can also choose to include or exclude comments, show heading numbering or set if preview scrolling should be synchronized with editor's text. Select Auto zoom when you want the preview to scale its content to the current width of the pane.

Preview auto updates it's contents every time Enter is pressed or when document is saved (Ctrl+S).

Trick: Select a block of text in editor, then open preview's context menu and select Update. Only selected text will be shown in the preview. Useful if you only want to print / export a part of the document.

Bug workaround: (May 2018) You can only resize preview pane by clicking and dragging top or bottom left edge of the pane.

Click Clack plugin

This plugin brings you typewriter sounds as already seen in WM2.

To enable sound scheme, open Command palette and select Enable/Disable Typing Sounds. Then select the scheme from the list. Disable with Disable Typing Sounds.

Wordnik plugin

Wordnik plugin (if installed) lives in the module pane on the right side of the wm window. It shows:

  • Related words (synonyms, antonyms, reverse dictionary entries ...)
  • Definitions
  • Sample photos

for the currently selected text or (if nothing is selected) for the word under the cursor.

To lookup a word, select a word or a phrase, then hit Ctrl+Alt+T (Command+Alt+T on Mac). If you prefer mouse, click reload icon at the bottom of the plugin pane.

Wordnik plugin uses great and free APIs from http://wordnik.com. To use the plugin, your computer must be connected to the internet.

Recently (May 2018) Wordnik changed their API policy which limits number of API calls per single key. If you are using this plugin frequently consider applying for your own free API key at https://developer.wordnik.com/

Some tips & tricks:

  • Click a word in Wordnik plugin pane to substitute currently selected word.
  • Hold Control key and click a word in Wordnik plugin pane to lookup that word.
  • Hold Shift key and click a word to open Wikipedia entry for that word.
  • Click little camera icon at the top to get sample pictures for a word. Click right or left of the picture to get next / previous picture. Shift + click picture to open Google images search page for the given word. Click camera icon again to hide picture section.
  • Click right or left at the top of the Wordnik pane to toggle available definitions for a word. Words in definition section are clickable too, so you can easily make a lookup for a given word.
  • package.json file contains some general plugin options. Explore.

Pomodoro timer plugin

The Pomodoro Technique is a popular time management method. See: http://cirillocompany.de/pages/pomodoro-technique for more info.

Pomodoro plugin (if installed) shows info at the top left corner of the wm window, but only when writing session is in progress (see: Session indicators section). It will show the following data:

  • Number of pomodoros completed
  • Red dots for all completed pomodoros (the size of the dot shows you how productive you were relative to other pomodoros; mouse over the dot will show you the exact number of words written for that pomodoro)
  • Number of words written for a current pomodoro
  • Minutes left for a current pomodoro

Default duration sequence:

  • 25 minutes - work
  • 5 minutes - short break
  • repeat 3x ...
  • 30 minutes - long break after 4th finished pomodoro

You can customize the sequence in package.json file, pomodoro_sequence setting.

To stop pomodoro timer, open Command palette and select Progress: Stop Current Session.

Auto replace plugin

This is a simple plugin that extends built in expandable snippets functionality. You can use it to automatically replace predefined strings with new ones after space is pressed. For example:

Replace two minus signs -- with en dash, three minus signs --- with em dash, ... with ellipsis sign. Type two consecutive straight quotes "" to replace them with a pair of square quotes »«.

Trigger / replacement pairs are defined in plugins/Auto_replace/package.json file, in triggerReplacementPairs property. You can edit existing or add your own pairs.

Typewriter Scrolling Plus plugin

Due to stability issues this plugin was demoted to "Experimental" status and removed from the download bundle (May 2018).

This plugin extends built in typewriter scrolling. When active, cursor not only stays fixed horizontally but also vertically.

Cursor always stays fixed in the center of the screen and the text moves left and right. Like a sheet of paper in the typewriter does. This only works in full screen mode with all panes hidden.

To enable / disable this feature, open command palette and select: Toggle Typewriter Scrolling Plus on / off.

Stamina bar plugin

Stamina bar plugin encourages you to write more and procrastinate less. Enable or disable it via Command palette - Stamina bar: Toggle on/off). When ON the right edge of the screen will show a bar that will raise as you type and fall when you are not active. Your goal is to keep it high and never allow to reach the bottom again. A little tick will show you the highest position you reached.

There are some setting in the plugins/Stamina_bar/package.json file:

"options": {
	"bar_position": "right",
	"bar_orientation": "bottom",
	"level_down_after_seconds": 5,
	"level_up_after_seconds": 7
}

Note that level_down_after_seconds setting must always be lower than level_up_after_seconds.

German thesaurus plugin (by ckosmowski, not preinstalled!)

This is a Plugin for Writemonkey Version 3. It provides Thesaurus functionality in german language. (Currently only synonyms) directly in a contextmenu. It uses the API of http://openthesaurus.de

Download from: https://github.com/ckosmowski/wm3-german-thesaurus

License

Writemonkey 3 is a freemium software. That means that it is free to download and use on as many machines as needed. There are, though, some goodies, namely plugins, that are only available to donors. Donors are those who supported the project (via PayPal) with any amount, excluding infinitesimal amounts as 0,001 EUR and such. Your donation goes straight to the sole developer that keeps this project alive. Thanks!

To donate, open Command palette and search for Support Writemonkey via PayPal command. Or simply click here. PayPal accepts all major credit cards and payment is possible even without PayPal membership.

Since WM3 is a complete rewrite, donor keys that were provided for WM2 are not valid for WM3.

WM3 is not open source, as mistakenly stated many times, but anyone can add to wm by developing 3rd party plugins.

💓🐒

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.