The Cordelia Manual

This manual covers Cordelia 1.0 in full: every menu command, shortcut, setting, and markdown rule the editor knows. If you want to know why Cordelia works the way it does, read the user guide first. This page is for when you need to look something up.

Getting started

Requirements

Cordelia runs on macOS 14 (Sonoma) or later. It is free on the Mac App Store, with no account, subscription, or in-app purchase.

First launch

When Cordelia opens, it shows the standard macOS Open panel instead of an empty window. From there you can:

• Choose an existing file to open, or
• Click New Document to start a blank one.

Once a document is open, ⌘N creates another and ⌘O opens the panel again.

What Cordelia opens

Cordelia opens plain-text files with these extensions: .md, .markdown, .mdown, .mkd, and .txt. You can also drag a file onto the Dock icon, or choose Cordelia from Open With in Finder.

Files must be UTF-8 text, which is what nearly every modern editor writes. A file in another encoding will not open (see Troubleshooting).

Documents and windows

Cordelia is a standard Mac document app, so most of what you know from TextEdit or Pages applies here.

One window per document

Each document gets its own window, and you can have as many open as you like. They appear in the Window menu. Cordelia has no library, sidebar, or tabs of its own. To keep related files together, use Finder folders.

Saving

• Autosave. Your changes are saved as you work. A dot in the window’s close button means there are changes not yet written to disk.
• New documents are saved as markdown (.md) the first time you press ⌘S.
• Plain-text files stay plain text. A .txt file you open is saved back as .txt.
• Your bytes are preserved. Cordelia saves exactly the text in the window. If a file began with a UTF-8 byte-order mark, the mark is kept when you save.

The File menu

Everything else is in the standard File menu:

• Duplicate (⇧⌘S)
• Rename… and Move To…
• Revert To, for returning to the last saved version or using Browse All Versions… to go back further
• Open Recent

You can also click the document’s title in the title bar to rename or move it. ⌘-click the title to see where the file lives.

Closing and quitting

If you close a document that has unsaved changes, Cordelia asks what to do. When you quit, macOS lets you review any unsaved documents first. Windows that were open when you quit reopen the next time you launch Cordelia.

Window size

Cordelia remembers each document’s window size and reopens it at that size. New and untitled documents open at the size you last used. Windows have a minimum width so that the text column always fits, even at the largest font size.

The editor

The page

Your text sits in a centered column about 66 characters wide, which is a comfortable line length for reading. Resizing the window changes the margins around the column, not the line length. The window behaves like a single sheet of paper: the title bar blends into the page, and a thin rule appears under it only once you scroll.

Type and appearance

The editor uses JetBrains Mono, which is bundled with the app, so you don’t need to install anything. The rest of the interface uses the system font. Cordelia follows your Mac’s Light or Dark appearance automatically.

You can change the font size and line spacing in Settings, but not the typeface or the column width.

Syntax markers

Every character you type stays on screen. Markdown symbols such as **, >, and ` are drawn in a faint gray, so the formatted text stands out while the markup stays visible and editable. Nothing is hidden, and there’s no separate preview mode.

Word count

The bottom-right corner shows how many words the document contains, updated whenever you pause typing. Markdown symbols, list numbers, and code-fence lines aren’t counted, but the words they format are. For example, **bold** counts as one word. Text inside code blocks and frontmatter is counted.

Undo

Undo (⌘Z) and Redo (⇧⌘Z) work as usual, including for the formatting commands and for the list markers Cordelia adds when you press Return.

Markdown reference

Cordelia styles the parts of markdown that prose writers use most. Everything else stays as plain text in the editor and is still valid markdown for any other tool you use.

Details worth knowing

• Headings need a space after the # marks, as in # Title. Text like #hashtag stays plain.
• Underscores inside words stay literal. Something like file_name_here doesn’t turn italic. Asterisks can still emphasize part of a word.
• Nothing is formatted inside code. Within a code span or code block, **, #, and every other symbol is shown exactly as typed.
• Code spans stay on one line. An inline code span can’t continue onto the next line.
• Code fences start at the beginning of a line. An opening fence can name a language in letters only, as in ```swift. The block ends at the next ``` line, and a fence with no closing line isn’t treated as code.
• Lists nest by indentation. Each tab or each two spaces adds one level, up to five levels. Deeper items are shown at the fifth level.
• Link titles are supported. You can write [text](https://example.com "Title"). The link text can’t span lines or contain brackets.

Not styled

These stay as plain text in the editor: tables, footnotes, task lists (- [ ]), reference-style links, horizontal rules, underlined (setext) headings, and raw HTML. Your files can still contain them, and other markdown tools will handle them as usual.

Formatting commands

The Format menu saves you some typing by inserting markdown symbols for you. It doesn’t switch Cordelia into a rich-text mode.

The heading commands act on the whole line, wherever the cursor is in it. If the line is already a heading, its level is changed rather than adding more # marks. For levels 4–6, type the # marks yourself.

To remove formatting, delete the markdown symbols. They’re ordinary characters.

Lists and quotes

Pressing Return in a list or blockquote starts the next line for you:

• Bulleted lists: the next line gets the same marker and indentation.
• Numbered lists: the next line gets the next number, so 3. is followed by 4.
• Blockquotes: the next line starts with >

To end the list, press Return again on the new, empty item. Cordelia removes the empty marker and leaves the cursor on a plain line.

Some things to know:

• Each continuation is a single step, so ⌘Z removes the new line and its marker together.
• Return behaves normally inside code blocks and frontmatter, even on lines that look like list items.
• Return also behaves normally when the cursor is inside the marker itself, for example before the -.
• Numbers aren’t renumbered later. If you insert an item in the middle of a numbered list, the numbers after it stay as they were. Most markdown tools number lists by position anyway.

To nest an item, add a tab or two spaces at the start of the line. The continued line keeps the same indentation.

Finding your way

Go to Heading ⌥⌘O

View ▸ Go to Heading… shows your document’s outline as a menu at the top of the window.

• Headings are indented by level.
• A checkmark shows which section the cursor is in.
• You can type the first letters of a heading to jump to it in the menu.

When you choose a heading, Cordelia scrolls it to the top of the window and puts the cursor at the end of the heading line, so pressing ↓ moves into the section. Long headings are shortened in the menu. Headings inside code blocks and frontmatter are left out. If the document has no headings, the menu says No Headings.

Find

Find opens the standard macOS find bar at the top of the window. It also handles replacing text, ignoring case, and whole-word matching. Find searches only the current document. To search across files, use Spotlight or Finder.

Typewriter Scrolling ⌥⌘T

View ▸ Typewriter Scrolling keeps the line you’re typing at a fixed height in the window, a little above the middle, and scrolls the page past it like paper through a typewriter. Your eyes stay in one place, and there’s always room below the line you’re writing, even at the end of the document.

• It’s off by default.
• The setting applies to every open window and is remembered between launches.
• When you turn it on or off, the page glides into its new position. After that, typing moves the page line by line.
• With it on, Go to Heading brings the chosen heading to the typing line instead of the top of the window.

Spelling

Cordelia uses the macOS spell checker. Words it doesn’t recognize get the usual red underline. Right-click one to see suggestions, choose Learn Spelling, or choose Ignore Spelling.

What Cordelia never does

The spell checker only flags words. Cordelia turns off every macOS feature that changes text by itself:

• No autocorrect
• No automatic text replacement
• No smart quotes or smart dashes
• No automatic capitalization
• No grammar checking

Turning it off

Spell checking is on by default. To turn it off, use either of these:

• Settings (⌘,) ▸ Check spelling while typing
• Edit ▸ Spelling and Grammar ▸ Check Spelling While Typing

Both control the same setting, which applies to every open document.

What gets checked

• Frontmatter isn’t checked, so keys like slug: and toc: don’t get underlined.
• Code spans and code blocks are checked, so unusual names in code may be underlined. You can ignore those underlines, or choose Learn Spelling for words you use often.

When underlines appear

On macOS 26 and later, the spell checker underlines a word when you type a space after it. If you edit a word and then click or arrow away without typing a space, the underline may not appear until you type more or reopen the document. When you open a document, the whole thing is checked. This is how the macOS spell checker works, and TextEdit behaves the same way.

Frontmatter

Many publishing tools, such as static site generators and note systems, read metadata from a YAML block at the top of a markdown file:

---
title: The Storm
slug: the-storm
tags: [lear, act-three]
---

The prose starts here.

Cordelia treats this block as metadata, not part of your text:

• It’s shown in a dimmer color, with extra space before the text that follows.
• No markdown is styled inside it.
• It isn’t spell-checked.
• It doesn’t appear in Go to Heading.
• It’s left out of exports.

How Cordelia recognizes frontmatter

A block counts as frontmatter only when all of these are true:

1. The first line of the file is exactly ---.
2. A later line of --- or ... closes the block.
3. Every unindented line between them looks like YAML. That means a key: value pair, a list item (- item), or a comment (# note).

The third rule prevents mistakes. A manuscript that opens with a --- scene break and has another one later isn’t treated as metadata. Otherwise its opening pages would be dimmed and dropped from your PDF.

Unquoted keys can’t contain spaces. Without that rule, a line like Chapter One: The Storm would look like metadata. If you need a key with spaces, put it in quotes: "post title": Lear. Indented lines are always accepted, so multi-line values and nested keys work.

If the block is never closed, everything below the opening --- is treated as ordinary text.

Exporting PDF and HTML

The editor is where you write. Export produces a typeset copy for other people to read: a critique group, an editor, or a printer.

How to export

1. Choose File ▸ Export as PDF… (⇧⌘E) or File ▸ Export as HTML…
2. Choose a name and location. The name starts out as the document’s name.
3. If you want line numbers, check Line numbers in margin. Cordelia remembers this choice for next time.
4. Click Save.

Only one PDF export can run at a time. If you try to start another, Cordelia beeps. If an export fails, an alert explains why.

How the export looks

• Type: 12-point serif text with generous line spacing. Code is set in JetBrains Mono.
• Headings: levels 1–3 are slightly larger than the text. Deeper levels are bold at text size.
• Margins: one inch on the top, bottom, and left. The right margin is 1¾ inches, leaving room for handwritten notes.
• Page numbers: every PDF page has a small page number centered at the bottom.
• Paper size: PDFs use your Mac’s default paper size.
• Color: the page is always white, even if your Mac uses Dark Mode, because exports are meant to be printed.

Your line breaks are kept

The export breaks lines exactly where your file does. A blank line starts a new paragraph. Many markdown tools join consecutive lines into one paragraph, but Cordelia doesn’t, so the export keeps the layout you see in the editor.

Line numbers

With line numbers turned on, each line of text gets a small number in the left margin, so a reader can refer to “line 142.”

• Numbering starts at 1 and has no gaps.
• Blank lines, headings, code fences, and frontmatter aren’t numbered, so line 3 is always the third line of text.
• Lines inside lists, quotes, and code blocks are numbered, and all the numbers line up in one column.

What’s included

• Links work in both PDF and HTML. Readers see the link text, which they can click.
• Images aren’t embedded. The ![alt](src) markup is printed as written.
• Frontmatter is left out entirely.
• Formatting follows the editor’s rules exactly. Anything Cordelia doesn’t style in the editor, such as a table, appears in the export as the text you typed.

The HTML file

HTML export saves a single, self-contained file. The page’s style and its font are built into the file, so it looks the same anywhere you open or send it.

Settings

Open Settings with Cordelia ▸ Settings… or ⌘,. Changes apply right away to every open document.

Font size and line spacing change only how text looks in the editor. Exports always use the fixed typesetting described under Export. Typewriter Scrolling is in the View menu rather than Settings, and it’s remembered too.

Keyboard shortcuts

All the standard macOS text-editing shortcuts also work: moving by word or line, selecting, and Emacs-style keys like ⌃A and ⌃E. Export as HTML has no shortcut.

Troubleshooting

A file won’t open

Cordelia reads UTF-8 text only. Files saved in an older encoding, such as Mac Roman or Windows-1252, will fail to open. To fix this, open the file in TextEdit, choose File ▸ Duplicate, and save the copy with the encoding set to Unicode (UTF-8).

The top of my document is dimmed and missing from the PDF

Cordelia is reading it as frontmatter. If it isn’t metadata, change the first line so it isn’t exactly ---. For example, add a blank line above it, or use *** for a scene break instead.

Prose is showing up as code

Code fences pair up in order, so one stray ``` line pairs with the next fence and turns everything between them into code. Delete the stray fence, or add the missing one.

A misspelled word isn’t underlined

Type a space after it, keep writing, or reopen the document (see When underlines appear). Also check that spell checking is turned on in Settings.

Typing feels slow in a very long document

Cordelia restyles the whole document each time you pause. On documents several thousand lines long, you may notice a brief pause. Splitting a book into one file per chapter avoids this, and it also makes the files easier to work with in other tools. If you hit this in a document of reasonable length, please let us know.

My list is nested deeper than it looks

Lists are drawn up to five levels deep. Anything deeper is shown at the fifth level but stays exactly as you typed it in the file.

Where is the preview?

There isn’t one. The editor already shows the formatting, and Export as PDF shows the finished, typeset version. The user guide explains why.

Getting help

Write to [email protected]. A good bug report includes:

• The text that caused the problem, or a short sample. Attaching the file itself is often easiest, since it’s plain text.
• What you expected to happen.
• What happened instead.
• Your version of macOS.

Back to top ↑