Tutorial

This tutorial walks you through Todtler by example. Each chapter focuses on one area. Some features mentioned here are only available in the latest builds of Todtler, which are available in the section Latest builds on the Download page.

  1. Getting started: the basics
  2. Advanced functions
  3. Expert functions
  4. Working with the Markdown format
  5. Working with the Fountain format

Shortcuts at a glance — press CTRL SPACE at any time inside Todtler to open the full shortcut reference. Press ? and T inside that screen for the in-app tutorial.

1. Getting started: the basics

Opening and saving

Start Todtler with a filename on the command line:

todtler my-notes.odt

If the file exists it opens immediately. If it does not, a new empty document is created with that name ready to save. Without a filename you get an untitled document.

To open a file while already inside Todtler, press ESC O. A file browser opens. Use ↑ ↓ to move, Enter or → to enter a folder, ← or Backspace to go up to the parent folder. Press Enter on a file to open it. Type any letter to jump to the first matching filename. Press / to search file contents: Todtler scans all files in the current folder and lists matches ranked by hit count.

To create a new document without leaving Todtler, press ESC N. By default the new document is pre-named with the current timestamp (YYYYMMDD-HHMMSS.odt), so your first ESC S saves it without asking for a name. The extension used depends on your default_extension setting (see Expert functions). If you prefer to name it yourself, set newdoc_timestamp: no in your config (see Expert functions). If you have unsaved changes, Todtler asks whether to save them first.

To save, press ESC S. If the document has no name yet, you will be prompted for a filename. Press ESC A to save under a different name (Save As).

Typing and moving around

Just start typing. The cursor moves with the arrow keys. Home and End jump to the start and end of the current line. Page Up and Page Down scroll through the document. ESC [ moves to the very first line; ESC ] to the last.

Ctrl Shift ← and Ctrl Shift → move the cursor one word at a time and extend a selection as they go.

Backspace deletes the character before the cursor. Delete removes the character at the cursor. ESC L deletes the entire current line.

When you press Enter at the end of a line that starts with - , the next line automatically begins with - too. Pressing Backspace at the start of that empty list item removes the prefix.

Finding text

Press ESC F to open the Find prompt. Type a word and press Enter. Todtler jumps to the first occurrence and shows:

Found 'word' at line 7  (← prev  → next)

While that message is visible, press → to find the next occurrence and ← to find the previous one. Any other key exits find mode. The search term is remembered; the next time you press ESC F the prompt pre-fills with it. Press Backspace once to clear the remembered term.

To replace text, press ESC R. You will be asked for the search term, then the replacement. All occurrences in the document are replaced at once.

Undo and redo

ESC U undoes the last change. ESC W redoes it. Todtler keeps an unlimited undo history for the session.

Quitting

Press ESC Q. If you have unsaved changes Todtler asks whether to save (y), discard (n), or cancel (c).

2. Advanced functions

Selecting text

Hold Shift and press an arrow key to extend a selection.
Shift ← / → selects one character at a time.
Shift ↑ / ↓ extends the selection by a whole line.
Press ESC M in case you want to cancel a selection.

Another way to select text is to drop a selection anchor at the cursor by pressing ESC M. Then navigate to the other end of what you want to select, either manually by using the arrow keys, or by using ESC F to find the end string of your selection.
Press ESC M again in case you want to cancel a selection.

Press ESC E to select the entire document.
Press ESC E again to deselect.

Clipboard

With a selection active:

Bold and italic

Position the cursor and press ESC B to toggle bold on or off for new text typed from that point. Press ESC I for italic. With a selection active, ESC B / ESC I applies the style to every character in the selection.

Page breaks (ODT only)

Press ESC P to insert a page break before the current paragraph. The break is stored in the ODT file and honoured by LibreOffice and other office suites when printing. Todtler shows it as a visual separator line:

─────────────────────────── Page Break ──

Page breaks, bold, and italic are ODT-only features. If you press ESC P, ESC B, or ESC I while editing a .txt, .md, or .fountain file, Todtler will show an error message instead of applying the unsupported formatting.

Chapters and folding

Any line that begins with # (one or more hashes + space) is a chapter header. Example:

# Introduction
This is the first paragraph of the introduction.
It can be as long as you like.

# Chapter One
Chapter one begins here.

# Chapter Two
Another chapter begins here.

With the cursor on or inside a chapter, press ESC # to fold it. The body lines disappear and the header shows:

# Introduction ──────── Folded (ESC # to unfold)

Press ESC # again to unfold. Press ESC * to fold or unfold all chapters at once: 

# Introduction ──────── Folded (ESC # to unfold)
# Chapter One  ──────── Folded (ESC # to unfold)
# Chapter Two  ──────── Folded (ESC # to unfold)

Folded chapters are view-only: Todtler prevents accidental editing of their hidden contents — the one exception is chapter swap (below): a folded chapter can still be moved with ESC ↑/↓, hidden contents and all. Folding a chapter only hides its own direct text — any sub-chapters underneath (see below) stay visible and can be folded independently with their own ESC #.

Chapter swap

With the cursor anywhere in a chapter, press ESC then the ↓ arrow to swap that chapter with the next one, or ESC then the ↑ arrow to swap it with the previous one. The whole chapter — header and body — moves as one block, and the cursor follows it. This works the same way whether the chapters involved are folded or not.

Chapters can be nested using more # characters: ## is a sub-chapter of the nearest preceding #, ### a sub-chapter of the nearest preceding ##, and so on. Example:

# Chapter One
## One Sub One
## One Sub Two

# Chapter Two
## Two Sub One

Chapter swap only ever swaps chapters at the same level, under the same parent — a sub-chapter never swaps past the chapter it belongs to. With the cursor on # Chapter One above, ESC ↓ moves the entire chapter — including its sub-chapters — below # Chapter Two. With the cursor on ## One Sub One, ESC ↓ only reorders it against ## One Sub Two, still inside Chapter One; pressing it again shows "No next chapter at this level to swap with.", since there's nothing left to swap with inside that parent.

tGrep — filter view

Press ESC G (or Ctrl G) to open the tGrep prompt. Type a search string and press Enter. Todtler immediately folds every line that does not contain the string, leaving only matching lines visible — exactly like grep output, but inside your document. Matches are highlighted in the visible lines (cyan background by default).

Example: press ESC G, type TODO, press Enter. Every line without TODO disappears. The status bar shows:

tGrep 'TODO': 3 line(s) shown, 147 hidden.

The arrow keys keep working normally — they skip over hidden lines so you move only between visible matches.

To reveal a single hidden line, navigate to it with the arrow keys and press ESC G again. To restore all hidden lines at once, press ESC *. You can also press ESC G and submit an empty string to clear the filter.

tGrep is case-sensitive by default. Match highlight style and case sensitivity are both configurable — see Expert functions.

Opening a different document (ESC O) or inserting one (ESC D) clears any active tGrep filter.

Inserting another document

Press ESC D to open the file browser in insert mode. Choose an .odt, .txt, .md, or .fountain file. Its content is pasted at the current cursor position. Press / inside the browser to search by file content, just as in ESC O.

Zoom (terminal font size)

Press ESC + to increase the terminal font size and ESC - to decrease it. ESC 0 (zero) resets to the default. This changes only the view, the document itself is not affected. Zoom is supported in kitty, xterm, and VTE terminals.

Typewriter mode

Press ESC T to toggle typewriter mode. In this mode the cursor stays fixed near the bottom of the screen while the text scrolls upward as you type, just like paper feeding through a traditional mechanical typewriter.

Hiding the title and status bars

Press ESC H to cycle through bar visibility:

3. Expert functions

Configuration files

Todtler keeps two plain-text config files, both created automatically on the first run:

~/.config/todtler/todtler.conf   — editor settings
~/.config/todtler/keys.conf      — key bindings

Both use the same simple INI format:

# This is a comment
[section]
setting: value

Open either file in any text editor, make your changes, save, and restart Todtler. The files are self-documenting: every setting has a comment explaining its purpose and valid values.

Customising keyboard shortcuts

Every shortcut can be remapped in keys.conf. The file is self-documenting: every action has a comment above it. The help screen (ESC ?) shows current bindings.

The [special keys] section lets you change the two meta-keys that drive command mode:

[special keys]
# Opens the help / shortcut reference screen.
help_key: CTRL_SPACE

# Activates single-letter command mode.
action_key: ESC

Valid values for both: ESC   F1–F19   CTRL_SPACE

Text expansions

Paste a fixed string of text (a character name, a place, a smart-quote character) with a single keystroke. Define expansions in ~/.config/todtler/expansions.conf (created automatically, with commented-out examples, on first run):

[expansions]
Q: "Quetzalcoatl"

Expansions are a two-key sequence, exactly like the built-in ESC-letter commands: press expansion_key, release it, then press the letter the expansion is bound to. Do not hold expansion_key down while pressing the second key.

expansion_key defaults to ESC and can be changed at the top of expansions.conf:

expansion_key: ESC

Valid values: ESC   F1–F19   CTRL_SPACE

Priority: when expansion_key is ESC (the default), pressing ESC then a letter that has an expansion bound to it always inserts the expansion's text, even if that letter is also a built-in ESC-command. The built-in command becomes unreachable via ESC while the expansion is defined; it remains reachable via its Ctrl+key binding, if it has one.

Recommended convention: bind expansions to UPPER CASE letters. Built-in ESC-commands respond to both cases by default: ESC q and ESC Q both Quit, for example. Binding an expansion to the upper-case letter claims it for your own use while leaving the lower-case form free for the built-in command.

Restart Todtler after editing expansions.conf.

Cursor style

Edit ~/.config/todtler/todtler.conf to change the cursor:

[display]
cursor_type: bar
cursor_blink: no

cursor_type options: block (default), underline, bar
cursor_blink: yes (default) or no

tGrep options

Two settings in the [editing] section control tGrep behaviour:

[editing]
tgrep_highlight: color
tgrep_case: sensitive

tgrep_highlight: color (default — cyan background on matches) or inverse (swap foreground and background)
tgrep_case: sensitive (default) or insensitive (match regardless of letter case)

Default file extension

When you save a document without typing a file extension, Todtler appends one automatically. The default is .odt, but you can change it in todtler.conf:

[general]
default_extension: md

Valid values: odt   txt   md   fountain

This setting also controls the extension on timestamp filenames created by ESC N. With default_extension: md, pressing ESC N gives you a file named YYYYMMDD-HHMMSS.md. If the default is a plain-text format and your document contains bold, italic, or page breaks, Todtler will warn you that those will be lost before saving.

Syntax highlighting

Todtler can colour your text based on patterns you define — per file type. Each extension gets its own config file in ~/.config/todtler/:

~/.config/todtler/md.conf
~/.config/todtler/fountain.conf

Both files are created automatically with sensible defaults the first time you open a file of that type. Open them in any text editor to see, add, or modify rules. Restart Todtler after saving changes.

Each rule is a named section containing a pattern and a style:

[heading]
pattern: ^#{1,6}(\s|$)
style: cyan

[code_inline]
pattern: `[^`]+`
style: #88ff88

pattern is a Python regular expression matched anywhere in the line — all non-overlapping occurrences are coloured. Rules are checked top to bottom; the first rule to claim a position wins.

style accepts:

Syntax colour is purely cosmetic and never written to the file. Selection and tGrep highlights always take priority over syntax colour.

Create new document — filename behaviour

By default, ESC N opens a new document pre-named with the current timestamp (YYYYMMDD-HHMMSS.<ext>, where <ext> is your default_extension). To start without a filename instead, set:

[files]
newdoc_timestamp: no

With newdoc_timestamp: no, pressing ESC N gives you a blank, unnamed document. The first ESC S will then ask you to type a filename.

File browser — dotfiles

The file browser hides files and folders whose names start with a period by default. To show them:

[files]
hide_dotfiles: no

Unicode character insertion

Press ESC K to open the Unicode character picker (supported in foot, xterm, and compatible terminals). Browse or search the table, select a character, and it is inserted at the cursor.

Working with LibreOffice documents

Todtler reads and writes ODT files that LibreOffice creates and vice versa. Bold, italic, and page breaks spans round-trip correctly. Other rich formatting (headings, tables, images, colours, headers, footers) are not displayed or edited by Todtler; nor do they pass through untouched.

4. Working with the Markdown format

Todtler treats .md files as plain text: it reads and writes raw Markdown source without rendering it. This is deliberate: you see and edit exactly what will be in the file.

A Markdown document in Todtler looks like this:

# My Article

This is the opening paragraph. It can run across
multiple lines; Markdown collapses them when rendered.

## A subsection

- First bullet point
- Second bullet point
- Third bullet point

A paragraph with **bold** and *italic* words.

> A blockquote is just a line starting with >.

Todtler's chapter folding works here too. Any line starting with # (one or more hashes followed by a space) is treated as a chapter header and can be folded with ESC #. That includes ## (level 2) and deeper headings, not only top-level #.

Typical workflow

  1. Open or create a .md file: todtler article.md
  2. Write your content using standard Markdown syntax.
  3. Use # headers to divide the document into sections you can fold and unfold while writing.
  4. Save with ESC S. The file is plain UTF-8 text, ready for any Markdown processor, static site generator, or version control system.

Tips

Todtler does not auto-indent list items or insert Markdown symbols; you type them yourself. This keeps the editor predictable and the output exactly what you wrote.

ESC B and ESC I write ODT character styles, not Markdown asterisks. If you are writing Markdown, type **word** and *word* directly for bold and italic.

5. Working with the Fountain format

Fountain is a plain-text format for screenplays, designed to be readable as-is and convertible to industry-standard PDF by tools such as Highland, Fade In, or the open-source afterwriting and fountain-tools libraries.

Todtler edits .fountain files as raw text. A minimal Fountain screenplay looks like this:

Title: The Long Road
Author: Jane Smith
Draft: First

# ACT ONE

## The Village

EXT. VILLAGE SQUARE - DAY

A dusty square. A CART rolls past.

ELENA
(looking around)
Where did everyone go?

She walks to the well and peers in.

INT. TAVERN - NIGHT

Dim candlelight. MARCO sits alone.

MARCO
I have been waiting for you.

Key Fountain conventions

Typical workflow

  1. Create the file: todtler screenplay.fountain
  2. Write your title page key-value pairs, leave a blank line, then start the body.
  3. Use # ACT ONE, # ACT TWO etc. as top-level section markers. Fold them with ESC # to keep your overview while writing deep inside one act.
  4. Save with ESC S.
  5. Convert to PDF with your Fountain renderer of choice.

Tips

Fountain is case-sensitive for scene headings and character cues. Keep those lines in ALL CAPS.

A line that looks like a scene heading but should be treated as action can be forced with a leading period: .NOT A SCENE HEADING

A character cue that is not all-caps can be forced with @: @McGregor