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:

---

Tables — Create a grid of rows and columns for structured data, comparisons, or reference lists. Tables follow GitHub Flavored Markdown syntax and support full inline formatting inside each cell.

For insertion, editing, row and column management, pasting from spreadsheets, and export options, see the Tables guide.

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.

Editor Style

The look of the writing environment is controlled separately from how documents are published. Atlas includes seven built-in themes — Nifty, Typist, Oolong, Birds of Paradise, Solarized, Natural, and Monochrome — each with light and dark variants. Switch between them in Settings > Editor Styles; the change takes effect immediately.

You can also adjust text size and line height to suit your reading preference. For deeper customization — per-element colors, fonts, and marker styles — see The Theme Editor. To change the look of exported documents instead, see Custom Export Styles.

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. Use Cmd+F to show it or select Find in Document in the menu.

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.

Converting to and from Markdown on Copy and Paste

Atlas stores your writing as Markdown, but the Edit menu can move text in and out in other formats — converting on the way through — so you're not stuck hand-cleaning markup when you copy into or paste from another app.

Copy as

The default Copy (Cmd+C) copies your selection as Markdown. The Copy menu also offers Copy as:

• Plain Text (Option+Cmd+C) — the selection with Markdown markers stripped
• Rich Text — formatted rich text (RTF), for pasting into a word processor or email
• HTML — rendered HTML source

Paste from

The default Paste (Cmd+V) brings the clipboard in as Markdown. The Paste menu also offers Paste from to convert other formats into Markdown as they land:

• HTML — clipboard HTML converted to Markdown
• Rich Text — clipboard rich text converted to Markdown

The available options adjust automatically to what's on the clipboard and to the editor you're working in.

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 Theme Editor — Creating and customizing editor themes
• Tables — Adding structured tables to your documents
• The Inspector — Writing statistics and document outline
• Keyboard Shortcuts — Find, editing, and navigation shortcuts