Documentation - writemonkey/wm3 GitHub Wiki

Writemonkey 3

This document is work in progress. Things may change! Last updated: January 22th 2023 (for WM 3.3.0 - Moonwatcher)

Download Writemonkey >>

Writemonkey

Writemonkey

Why Writemonkey 3

Writemonkey 3 is the new incarnation of the original Windows only application that has been around since 2006. 17 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:

  • minimal yet powerful,
  • plain text only,
  • clean 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

Writemonkey 3.3.0 is stable . 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 (January 2023):

  • Some kind of cloud synchronization mechanism
  • Proper installation mechanism

Major goals for tests in January 2023:

  • 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 3.3.0)

Currently (v 3.3.0 / January 2023) 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 (Intel, Apple silicon)

(January 2023, version 3.3.0)

Since wm3 still lacks proper installer, setup on OSX High (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 (preferably use the first method, other two are less reliable):

  • Run from the terminal (replace [full path] with actual path):

sudo xattr -r -d com.apple.quarantine [full path]/writemonkey.app

OR

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

OR

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

Writemonkey 3.3.0 runs on Macs with M1 or M2 chips with Rosetta 2.

Installation on Linux systems

(January 2023, version 3.3.0)

If you have problems running wm3 on Linux you might find some tips @ https://github.com/writemonkey/wm3/issues/315 or https://github.com/writemonkey/wm3/issues/346.

Upgrade from previous version (for version 3.3.0)

To upgrade from previous version (like from 3.2.0 to 3.3.0) 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.

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 (backup triggers at the moment wm loses focus). Backup will store 2 versions - latest and the previous one marked with _OLDER in the filename. If you are restoring from older version remove _OLDER part from the filenames.

You can open database backup directory from within wm via command palette (Application: Open Directory with Database Backup Files).

Working with text files

Writemonkey 3.3.0 (January 2023) 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 Save as file & bind to document 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: Save as file & bind to document 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. You'll be asked if you want to keep the file or delete it.

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 for example 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.

Open setting files in the default JSON editor via the command palette using: Application: Open Setting Files in Default JSON Editor

Markdown

Writemonkey 3 is fully markdown compliant. 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 some additional non-standard syntax rules & settings you can use in WM3 (see below).

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).

Footnotes / endnotes

Use:

This is some text with a footnote/endnote[^1], and another[^2]

[^1]: This is footnote text
[^2]: This is another footnote text

The footnotes will appear as endnotes at the end of the document.

You can also define footnotes inline, like:

This is some text^[And this is a footnote]

Table of contents

Put

@[toc](Table of contents)

at the position where you want table of contents to appear when exporting.

Marked text

Example:

==this is marked text==

Forced empty lines

Natively HTML doesn't render multiple empty lines, the same way as it doesn't render multiple spaces. If you need blank lines in your exported document, use one space in an otherwise empty line:

Some regular text
[space][enter]
[space][enter]
[space][enter]
[space][enter]
Some other regular text

Normal indented paragraphs

In markdown paragraphs that start with a TAB or 4 spaces are interpreted as a code block. Some writers hate that as they like to manually indent paragraphs & want them to behave as normal text. If you are one of them, enable normal indented paragraphs in settings file - normal_line_indenting. That will override default markdown behavior. Off by default.

Convert tabbed lines to markdown table

Write:

first [tab] second [tab] third
first [tab] second [tab] third
first [tab] second [tab] third

select all lines and use Convert Selected Tab-separated Lines to Markdown Table from command palette to convert to markdown table.

You'll get:

| first |  second |  third |
|:--|:--|:--|
| first |  second |  third |
| first |  second |  third |

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!

Last 7 used commands are always at the top of the list & underlined. If you need more than 7, change that in the settings file - command_palette_num_of_recent_items

Font size and text area width

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

  • To set font zoom factor: Hold Ctrl + scroll wheel or use Ctrl+6 / Ctrl+7
  • To set text area width: Hold Alt + 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.

Clean text command

Clean text command will remove redundant spaces, empty lines, and tabs from the document or selection. Use the command palette or Ctrl+K,C shortcut.

The command can optionally also normalize all quote marks to straight quote marks. You can disable that in the settings file ("clean_text_straighten_quotes": true/false).

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 project/document name, word count and current time.

Additional indicators next to the document name are:

  • Document changes are not saved indicator - big dot icon (you can disable that in the settings file - show_not_saved_indicator)
  • Document is read only indicator - padlock icon
  • Document is linked to the file indicator - chain link icon

You can set which count unit to show in info bar (word count is default). Click count label at the bottom right corner to select preferred unit. You can choose from:

  • words
  • characters without spaces
  • characters with spaces
  • sentences
  • paragraphs / lines
  • standard pages (customize in settings file)
  • reading time (customize in settings file)
  • speaking time (customize in settings file)

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, 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.

Since version 3.0.10 fonts are no longer part of the theme files. Chose your preferred font from the command palette: View: Set Themes, UI filters, Font & Line Spacing

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.3.0 (January 2023) features new improved themes - Default, Default dark, Fresh mint, Snow white, Blue, Grey, Beige, Pine, Old typewriter, Industrial black, Red, Terminal and Black mamba. WM3 also supports background images.

Open current theme file in the default CSS editor via the command palette using: View: Set Theme, UI filters, Font & Line Spacing.

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 View: Set Themes, UI filters, Font & Line Spacing 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.

Set brightness and sepia via command palette in View: Set Themes, UI filters, Font & Line Spacing

Fonts & Line spacing

Writemonkey comes with a handful of fonts that can be used out of the box:

  • Hack Mono (default)
  • Vera Mono
  • Operator Mono
  • Courier Prime
  • Liberation Mono
  • Iosevka
  • Truetypewriter Mono

Change the font via command palette using View: Set Themes, UI filters, Font & Line Spacing, where you can also set preferred line spacing.

If you want to use fonts that are installed on your computer, open the settings file, search for:

"main_font_list": ["Hack Mono", "Vera Mono", "Operator Mono",
"Courier Prime", "Liberation Mono", "Iosevka", "Truetypewriter Mono"],

and add the font family name you want to use. After the restart new font will appear on the font list. Use monospaced fonts for the best result.

It is not recommended to change the settings_main.json file directly. Copy your changes into settings_main_user.json instead.

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.

Alternatively you can create _default.js file which is valid for all templates.

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 (January 2023) existing templates need some 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 right click it and select Restore deleted document. Right click the Trash folder and select Empty trash to permanently remove all deleted documents.

Projects

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.

Create new subproject by right clicking the parent project name and select New subproject. You can have as many subproject levels as you want.

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 Right click project folder and select Count words from the menu to show word and character count for all documents in the project/folder. Note that documents from subprojects/subfolders are not included in the count.

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.

Reordering projects via drag&drop is not supported at this point, but you can right click the project and choose Move to the top of the list.

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)

Right click document tile to get the document context menu with some options. You can, for example, mark document as Read Only to protect it from unwanted changes or mark it as a favourite.

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

Double click document tile to fold / unfold all headings in that document.

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

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 map marker 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
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.

Marked text Parts of text that are marked with == ==

Footnotes Markdown footnotes

Right click Jumps pane to hide or show jump categories.

Double click Headings item to fold / unfold that heading.

Ctrl + click any jump item to Focus it.

Keyboard shortcuts

Keyboard shortcuts are not customizable at this point (January 2023).

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 + Shift + S - Save as file & bind to 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 + F8 - Toggle sentence breakup mode on / off
  • Ctrl+F9 - Toggle anchored reading on / off
  • Ctrl+Shift+T - Toggle typewriter scrolling on / off
  • F12 - Show / Toggle / Hide right pane modules
  • Ctrl + Q - Quit / Close Writemonkey
  • 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
  • Cmd+Opt+I - Ask AI (GPT-3) / AI helper plugin

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 and multilevel lists (markdown)
  • Ctrl + 8 - Toggle fold / unfold current heading or multilevel list (markdown)
  • F5 - Toggle collapse range (paragraph or selection)
  • F6 - Toggle segment focus (paragraph or current sentence)

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 + Shift + H - Copy clean html (Preview plugin must be installed)
  • Ctrl+K,C - Clean text / document or selection
  • Ctrl + A - Select all
  • Ctrl + D - Select next occurrence
  • Ctrl + Enter - Insert line after
  • Ctrl + Shift + Enter - Insert line before
  • Ctrl + Shift + โ†‘ / Ctrl + Cmd on Mac - Move line up
  • Ctrl + Shift + โ†“ / Ctrl + Cmd on Mac - 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 Upper case
  • Ctrl + K,L - To Lower case
  • Ctrl + K,T - To Title case
  • 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 + E - Marked text (extended markdown)
  • Ctrl + backspace - Delete word left
  • Ctrl + delete - Delete word right
  • TAB - Increase indent (when editing markdown lists)
  • Shift + TAB - Decrease indent (when editing markdown lists)
  • Alt + Up - Increase markdown heading level
  • Alt + Down - Decrease markdown heading level

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
  • Jumps pane - show / hide jump categories
  • Word count in info bar - unit selection menu
  • Trash - empty trash
  • Search field in document pane - last searches
  • Tile in repository - repository options
  • Search field in repository - filter by type 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 the Command palette.

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

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 include full path, for example on Windows:

c:/some_dir/photo.jpg

becomes:

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

On Mac computers you similarly use:

![](/some_dir/photo.jpg)

You can also drag and drop local images directly into WM editor.

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);

The macro above, 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=";

Another example:

/* Copy with single breaks */

var e = _editor;
if (e.somethingSelected()) {
	var q = e.getSelection();
} else {
	var q = e.getValue();
}
q = q.replace(/\n{2,}/g, "\n").trim();
var clipboard = gui.Clipboard.get();
clipboard.set(q, "text");

The macro above fetches the contents of the current document or selection, then substitutes all double (or more) line breaks with single line breaks. It then stores the result in the clipboard.

There is no plugins API documentation at this point (January 2023) 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. If you make global snippet local again it is linked to the current document and not the one that was created in.

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

Cut snippet - Put content of the snippet in clipboard and remove from repository.

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 (or right click the search field). Sub menu with the following items pops up:

  • Current document (empty filter field); also shows all global snippets
  • Current project (@project); also shows all global snippets
  • Macros & Links (@macro)
  • Expandable snippets (@exp)
  • Images (@img)
  • All snippets (@all)

Alternatively you can type filter string into the repository filter field to get the same results. For example, type @all to show all snippets in the database or @exp to get a list of all expandable snippets in the database.

To search repository within certain snippet type:

@project john

this will, for example, search for snippets containing john but only within the current project.

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.

Folding multilevel lists

Multilevel lists like:

  • first level
    • second level
      • third level
      • third level

can also be folded / unfolded. The same logic and commands apply as for Header folding.

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.

Collapsed range goodies

Apart from standard collapsed text, you can also use F5 to show inline images, tables and Katex formulas:

A) Put cursor on a markdown image definition like:

![Monkey](https://ichef.bbci.co.uk/news/660/cpsprodpb/025B/production/_85730600_monkey2.jpg)

hit F5 and the image thumbnail replaces the image definition.

You can set thumbnail size in the settings file - collapsed_region_image_size.

B) Select markdown table definition like:

| Tables   |      Are      |  Cool |
|----------|:-------------:|------:|
| col 1 is |  left-aligned | $1600 |
| col 2 is |    centered   |   $12 |
| col 3 is | right-aligned |    $1 |

hit F5 and real rendered table will replace the textual definition.

C) Select Katex formula definition like:

$$$ \Huge E=mc^2 $$$

hit F5 and real rendered formula will replace the textual definition.

Use $$$ [formula] $$$ delimiters to mark that this is a Katex formula. If you want your formula to appear inline, like:

Some text $$ E=mc^2 $$ some other text ...

use double $$ as a delimiter. For more info on Katex see: https://katex.org/. Keep in mind that WM3 Katex delimiters are different than the standard ones.

D) Select paragraph marked as a comment:

// this is a comment blah blah blah

and hit F5 to show it in post-it note like manner.

Segment focus

Segment focus hides everything but selected text. Use F6 to enter focus mode.

  • Select the text and then hit F6 - you can now see and edit that selection only.
  • Put your cursor on a markdown heading and hit F6 - get focus on that heading and all of its subheadings.
  • If nothing is selected and you hit F6 - only current sentence remains visible. If there is no sentence under the cursor, you'll get empty screen.

When in focus mode, hit F6 again to exit focus mode. You can also click the "eject" 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.

Sentence breakup mode

One feature that also falls into "focus" category is Sentence breakup mode. When on (toggle with Ctrl+F8 or via command palette) sentences in paragraphs are shown line-by-line, separated by a divider. That way you get better insight into how your text is constructed and that makes editing, even reading easier. It is also easier to select individual sentences and move them around.

You can set the style of the sentence divider line in settings file - sentence_breakup_divider_style: solid/dotted/dashed.

Use sentence_breakup_dot_exceptions setting to add "dot abbreviation/acronyms" exceptions you use regularly so that they won't break the sentence, like: mr. mrs. ms. dr. e.g. etc. i.e. prof. ...

Anchored reading aka Bionic readings

Anchored reading mode revises texts so that just front parts of words are highlighted. This guides the eye over the text and make reading faster and more focused.

The feature mimics Bionic Readingยฎ. See https://bionic-reading.com for more info.

Settings file has some options:

"anchored_reading_min_word_length": 4,
// skip words shorter than
"anchored_reading_anchor_length": 0.5,
// 0 = whole words, 1 = beginning only
"anchored_reading_skip_words": 0,
// skip X words, 0 = do not skip

Use command palette or Ctrl+F9 to enable / disable.

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 recognizes 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 (or title) 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 (or keywords) 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.)

You can also use YAML style metadata delimiters:

---
title: some title
keywords: k1 k2 k3
---

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 from the list:

or

  • Download additional dictionary packs via https://github.com/titoBouzout/Dictionaries.
  • 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.3.0 - Currently there are problems with some Romance languages (Portuguese, Italian ...). 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 (January 2023).

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!

AI helper

(new in 3.3.0)

Jaanuary 10th, 2024: New version of the plugin (still work in progress) is available >>HERE<<.

The following description is for the new version. The WM 3.3.0 installation bundle includes an older version.

IMPORTANT! To use this plugin, you must first acquire your own API key for the service. Create an account at https://openai.com, create an API key and paste it into plugins/ai-helper/package.json:

"openAiApiKey": "your key here",

"AI Helper" is a simple plugin that integrates WriteMonkey with the popular AI assistant, GPT-3/4 (ChatGPT). You can write prompts and receive answers directly within WM.

Simply write your prompt in an empty line and ask AI for an answer (via command palette, or shortcut - Ctrl+Alt+I on Windows or Cmd+Opt+I on Mac). The answer will appear in a couple of seconds under your prompt as selected text.

If your prompt spans multiple lines, select those lines before issuing the command.

There are some advanced options available in plugins/ai-helper/package.json file. You can set different modes/identities:

{
	"name": "DEFAULT Markdown",
	"role": "You are a writing assistant.",
	"shortcut": "md",
	"description": "Default general AI, but with MD formatting",
	"prepend": "[Format your response using markdown. Use headings, subheadings, bullet points, and bold to organize the information. Return only the main response. Remove pre-text and post-text.]",
	"append": "",
	"settings": {
		"n": 1,
		"model": "gpt-4-1106-preview",
		"temperature": 0.6,
		"top_p": 1,
		"max_tokens": "auto",
		"frequency_penalty": 0,
		"presence_penalty": 0
	}
}

Or that one (very meta):

{
	"name": "Auto follow up chain",
	"role": "You are a helpfull assistant.",
	"shortcut": "af",
	"description": "Will automatically pose a follow up question after the answer",
	"prepend": "",
	"append": " Give me the answer, and then pose a question at the end that can provide further insights into the issue from a different point of view, but stay on the main topic from original question. Prepend this question with '...' and append it with '/af'",
	"settings": {
		"n": 1,
		"model": "gpt-3.5-turbo",
		"temperature": 0.6,
		"top_p": 1,
		"max_tokens": "auto",
		"frequency_penalty": 0,
		"presence_penalty": 0
	}
}

To use a specific AI identity, prepend or append your prompt with a slash and its shortcut (or select it from the command palette):

/md Write me an essay about a naughty monkey

Use =N at the beginning or end to define the quantity you need. For example:

What is disc golf? =5

will give you an answer 5 paragraphs long. If you want some other way than paragraphs to define quantities, change

"quantity_descriptor": " [give me {N} paragraphs] "

setting in package.json file.

The assistant will not remember your previous conversation when you post a new prompt. However, you can make it remember by adding an ellipsis (three dots) before the prompt. For instance:

... Make your previous answer more compact.

will continue conversation. As long as you use three dots, the context of the conversation will be retained.

You can combine commands:

... Explain your second paragraph =3 /md

Create your own identities by modifying the package.json file.

The new version uses the gpt-4-1106-preview model by default but you can set other models.

for each identity you want to use that model with.

Tip: To enhance your experience, use the "Segment focus" command (F6) to isolate the text provided by the AI. This will make it easier for you to review the text, make any necessary changes, and then exit Segment focus to integrate it seamlessly with your writing.

Tip 2: There is a special AI helper module in the right pane. It shows all your identities as clickable buttons and all your previous conversations. You can continue any previous conversation or copy it to a clipboard.

Tip3: New version (July 23) works with the clipboard. See Summarize from clipboard identity. You can of course create other identities that utilize system clipboard.

Disclaimer: The author of Writemonkey believes that AI assistants should be used as an aid to human writers, rather than as a replacement. If we become too dependent on such technologies, future generations may lose the ability to write effectively. And the Idiocracy will not just be a silly movie.

Pandoc plugin

(new in 3.3.0)

IMPORTANT! To use this plugin you must first install the free Pandoc universal document converter. You'll find the installation at https://pandoc.org.

With this plugin, you can convert your markdown to almost any file format you can imagine. There are some commands predefined in plugins/pandoc/package.json but you can add your own according to your needs (some expertise is needed for that, but Pandoc documentation is very good and extensive).

{
	"type": "export", // export or import
	"name": "Markdown to MS Word DOCX file on Desktop",
	"description": "MMD HEADER",
	"command": "-s -f markdown_mmd+hard_line_breaks+mmd_title_block+strikeout+task_lists+fenced_code_blocks+inline_notes -t docx -o {desktop}/{name}-{datetime}.docx", // tricky part
	"source": "editor", // editor, clipboard or file
	"target": "file", // editor, clipboard or file
	"attachGlobalOptions": false,
	"openInApp": true
}

Once you configure the plugin for your needs, importing or exporting text is just a few clicks away:

Open the command palette, search for Pandoc, and then select the command from the list.

You can also attach specific Pandoc instructions via the metadata block at the beginning of the WM documents. You must use YAML delimiters for this to work. For example:

---
title: Primordial life
subtitle: The silicon creatures
author: Jason Spofford
abstract: Primordial Life presents an environment ...
date: March 22, 2022
lang: en-US
pandoc: --number-sections --toc
...

Preview

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.

Trick 2: Enter the focus mode (F6) and preview will show focused text only.

Trick 3: Double click anywhere in the preview pane to update the preview.

Trick 4: Right click anywhere in the preview pan to open context menu with additional options.

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

Word frequencies

Shows word cloud and word frequencies for the document or selection. The plugin also shows positions of the words in the document.

Click the word on the list to mark the words in the document. To hide, click the empty space above the list.

package.json file contains some general plugin options like a list of STOP WORDS (defaults to English STOP WORDS) that are ignored when creating the frequencies list, maximum number of words shown etc.

Click Clack

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

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 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

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

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:

  • lnk - insert markdown link
  • img - insert markdown image
  • toc - insert markdown table of contents
  • ftn- insert markdown footnote

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

This plugin extends built in typewriter scrolling. When active, cursor not only stays fixed horizontally but also vertically. 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

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 (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.

This document was written & composed with Writemonkey 3.

๐Ÿ’