Writing with Markdown

Atlas uses a hybrid live-rendering markdown editor—rich elements like images, links, and formatting (headings, emphasis, lists, etc.) appear as you type, but markers for many of these items will remain visible and editable like other text.

Why Markdown?

Markdown is a lightweight markup language that you can use to add formatting elements to plain-text documents. It allows you to easily produce consistently formatted documents in various formats, like HTML, docx, ePub, and PDF, that are styled independently from how you prefer to write (and hide markers).

Documents created with Markdown are also easily portable, editable by any editor, and future proof. Where Atlas diverges from the standard Markdown spec to include additional features, it aims to align with conventions used by other popular editors for best compatibility.

You can read more about Markdown at the Markdown Guide.

Getting Started

To start writing, create a new text document from the Organizer using the + button, context menu, or the Cmd+N keyboard shortcut. The editor opens immediately, ready for text.

Formatting Reference

Atlas supports the following markdown syntax. Where available, keyboard shortcuts are listed for Mac and iPad with an external keyboard.

Headings

Use # symbols to create headings. Additional # symbols mean deeper levels.

Headings also appear in the Document Outline in the Inspector, giving you a clickable table of contents for long documents. See The Inspector for details.

Inline Formatting

Block Elements

Blockquotes — Prefix lines with > to create a blockquote. You can quote multiple lines together, too.

> This is a blockquote
> that spans multiple lines

Shortcut: Cmd+D

Ordered lists — Start lines with a number and period or parenthesis:

1. First item
2) Second item
3. Third item

Unordered lists — Start lines with a dash, star, or plus:

- First item
* Second item
+ Third item

Use Cmd+] to indent list items and Cmd+[ to de-indent.

Code blocks — Wrap multiple lines in triple backticks:

```
Your code here
```

Horizontal rules — Type three dashes on their own line to insert a visual divider:

---

Beyond Text

Atlas also supports images, links to other documents, annotations and footnotes, and equations for embedding LaTeX math expressions inline or as blocks — each covered in their own articles.

Formatting Controls

Both platforms provide quick-access formatting tools so you don't need to remember syntax.

iOS — Formatting Keyboard

A dedicated formatting keyboard appears above the system keyboard when editing. It adapts its layout for iPhone and iPad screen sizes, providing buttons for all text styles, headings, lists, blockquotes, horizontal rules, links, images, annotations, and footnotes.

Mac — Floating Formatting Bar

A formatting bar is anchored to the bottom of the editor, providing the same quick-access options. Toggle its visibility from Editor > Show/Hide Formatting Bar (Option+Cmd+K). It's enabled by default.

Escape Characters

Markdown lets you prefix a special character with a backslash to keep it literal — for example, \*not italic\* renders as *not italic*. Atlas highlights backslash escapes in the editor so you can see at a glance where you've used them, and strips the backslashes from the final output when exporting to HTML, ePub, or PDF, so readers see only the intended character.

Finding and Replacing Text

Atlas uses the system find bar in the Markdown Editor so you can search within the current document at any time.

The find bar shows a live match count and gives you case-sensitive and whole-word toggles. Toggle Replace in the find bar to reveal the replacement field — from there you can replace the current match or replace all matches in the document at once. Find and Replace is scoped to the document you're currently editing; to search across an entire project, use the Organizer's search field instead. See Tags and Search.

iOS and iPadOS

Open the editor's More menu in the toolbar and choose Find in Document. With an external keyboard attached, Cmd+F opens the same find bar directly.

macOS

Press Cmd+F in the editor to open the find bar. Use Cmd+G to jump to the next match and Cmd+Shift+G to jump to the previous match.

See Also

• Images and Sketches — Embedding images and creating sketches
• Linking — Connecting documents with internal and external links
• Annotations and Footnotes — Adding commentary and reference notes
• Math Equations — Embedding LaTeX math expressions
• Customizing the Editor — Themes, text size, and line height
• The Inspector — Writing statistics and document outline
• Keyboard Shortcuts — Find, editing, and navigation shortcuts