Markdown Editors for AI

Markdown editors for Mac. Why a Markdown editor is often needed for work with AI agents. Kinds of Markdown editors and viewers. Features found in Markdown editors.

Use a Markdown editor to read and edit the documents you use with an AI agent. Markdown is the plain text format AI agents read and write. A project that uses AI will have agent instructions, project plans, and work history saved in Markdown format and, while you can read the files with a text editor or an AI app, it's convenient to use a dedicated Markdown editor. Setting up project files this way is called spec-driven development, and it helps an agent finish work that takes more than one session.

The "Set Up Your Mac" apps offer to install a Markdown editor. This page explains why, what Markdown has to do with AI agents, and how Markdown editors differ, so you can choose one that suits your work. It is one topic in "Set Up Your Mac", my guide to setting up a Mac for software development. For everything else, see the complete Mac setup checklist.

Markdown editors in the "Set Up Your Mac" apps

The "Set Up Your Mac" app has screens to help you install an upgraded terminal application, a code editor, and Markdown editors. Software developers typically use a code editor such as Zed, VS Code, or Cursor, which can display Markdown files. However, code editors are overly complex and clunky for editing Markdown, with toggling between viewing and editing files. And code editors are less often used as AI agents take over writing code.

The "Set Up Your Mac" Markdown Editor screen offers to install a simple Markdown editor or an advanced "second brain" app for linked documents (called a personal knowledge manager, or PKM).

Nothing is selected until you choose, and an editor you already have is grayed out. Click "Skip" if you don't want either. The app installs your choice with Homebrew, and when setup is done, its last screen has a button to open each of the editors.

Why Markdown matters for AI work

What Markdown looks like

Markdown marks formatting with a few symbols, such as # before a heading, - before a list item, and ** around bold text. It is not a proprietary format; any app that can open a plain text file can open a Markdown file. Markdown adds formatting that communicates additional meaning, such as headings and lists, without requiring the hidden formatting code that makes proprietary apps such as Microsoft Word unsuitable for use by so many other apps.

Here is a short file an AI agent might write:

# Plan for the signup page

## Goal

Let a visitor sign up with an email address.

## Steps

- Add a signup form to the home page
- Save each address to the database
- Send a welcome email **within one minute**

In a Markdown editor, you see a document with a large heading, a bullet list and bold text, and the symbols are hidden or faded. In a plain text editor, you see every symbol. A short file is easy to read either way, but a long document full of symbols is tiring to read. CommonMark's Markdown reference shows all the symbols you can use.

The format AI agents use

AI chatbots such as ChatGPT display answers in the chat window and allow you to copy or download in Markdown. AI agents go further and directly save their work as Markdown files. The agents also use Markdown files for guidance. Claude Code reads its instructions from a file named CLAUDE.md, Codex reads AGENTS.md, and the instructions for an agent skill are in a file named SKILL.md. When you ask an agent to plan a task, research a question or record what it did, it writes a Markdown file. Markdown suits agents because it is plain text, which any program can read and change, and its headings and lists add a meaningful structure that you and the agent both understand.

Context that lasts between sessions

An AI agent remembers almost nothing from one session to the next. What carries over is what the agent finds in the project folder. The Markdown documents in the folder give the agent its context (the information it works from) in every new session. They can hold its instructions, the plan, the decisions you've made, and notes about work history. Developer Setup for Starter Projects shows how to set up a project folder this way, and Developer Setup for Agent Instructions explains the instruction files.

Your share of the work

In a Hacker News discussion in April 2026, some developers who work with AI agents said they now spend less time reading code and more time reading the Markdown files written by agents. Several developers built their own Markdown viewers to make it easy. That's why I say a Markdown editor is becoming more important than a code editor, especially when your role is directing an AI agent.

Agents also write too much. They pad documents, add things nobody asked for, and don't always separate a lasting decision from a passing remark. Documents go out of date as the work moves on, and an outdated document misleads the agent in its next session. So a developer must trim what the agent writes, and keep each document short and current. It's faster in a Markdown editor that shows the document clearly.

Kinds of Markdown editors

There are dozens of Markdown editors for the Mac, and they fall into rough groups according to intended purpose (use case). If:

You mainly read what an agent writes - use a simple Markdown editor.
You write long documents of your own - look at the writing apps.
You collect notes over months or years and want them linked - choose a personal knowledge manager.
You already use a code editor every day - see if its Markdown preview is sufficient.

Here I name the best-known products in each group, judged by how often people search for them and how often published comparisons include them, in October 2026. Prices and features change, so check each product's site before you choose.

Markdown viewers

A Markdown viewer renders text with Markdown formatting as a styled document for easier reading. Usually you need to jump back to raw text in another window to make edits.

A Markdown viewer is enough only if you read what an agent writes and never correct it. QLMarkdown, which is free, adds Markdown to the Finder's Quick Look, so you can select a .md file and press Space to see it formatted (open the QLMarkdown app once after you install it). Marked, a paid app now in its third version, shows a formatted preview of a file you edit in any other app and updates the preview each time the file is saved.

Simple Markdown editors

This is the category I recommend for work with AI.

A simple Markdown editor opens a file or a folder and lets you edit the formatted document directly. Headings look like headings as you type, and the symbols appear only where your cursor is, or not at all (this is often called WYSIWYG, for "what you see is what you get"). I often use ColaMD. Typora is the best known, a paid app with a one-time price. MarkText is a free, open-source editor that works the same way, though Homebrew stopped installing it in September 2026 because it fails Apple's security check for downloaded apps (Gatekeeper). Other simple editors, such as MacDown 3000 (free and open source), show the raw text with a formatted preview beside it. A simple editor suits anyone who wants to read and revise an agent's documents without learning a complex app.

Writing apps

Writing apps are made for writing prose, with distraction-free screens, careful typography, and export to Word, PDF or a web page. Ulysses, sold by subscription, keeps your writing in its own library, though it can also edit Markdown files in an outside folder, with fewer features. Bear, a notes app (free, with a subscription for syncing), keeps notes in its own database, and since April 2026 it has offered an MCP server, a connection that lets an AI agent read and write your notes. Zettlr, free and open source, is made for academic and long-form writing, with citations from a reference manager such as Zotero. iA Writer, a paid app with a one-time price on the Mac, works with Markdown files in any folder you choose.

Personal knowledge managers

A personal knowledge manager (a PKM, often called a "second brain") holds a library of notes that grows over months or years, with links between the notes. Obsidian is the leader, and it is free, for work as well as personal use (it charges only for optional syncing and publishing services). Your notes are Markdown files in an ordinary folder (Obsidian calls it a vault), and Obsidian adds links between notes, a graph of the connections, and thousands of plugins written by its users. Because a vault is a folder of Markdown files, many people open it in Claude Code or Codex and ask the agent to search, summarize or organize their notes. Until recently, I used Obsidian for research, record keeping and rough drafts, but now I use simpler Markdown editors with vault-like folders managed by AI agents. Another popular PKM is Logseq. It is free and open source, and organizes notes as outlines. Logseq's new version, in testing in October 2026, keeps notes in a database rather than as Markdown files.

Code editors

Code editors such as VS Code, Zed and Cursor open Markdown files beside your code and show a formatted preview in a separate pane. If you already use one every day, you may not need another app. A code editor also shows exactly which lines changed in a file, which helps when you check an agent's edits. The drawback is that you edit the raw Markdown and see the formatting only in the preview, which many people find awkward.

Editors made for working with AI agents

A new group of editors is made for the documents that people and AI agents share. All of them are less than a year old (in October 2026). These editors reload a document the moment an agent changes it. Some also show what the agent changed, let you comment on an agent's plan, or run an agent from inside the editor. Examples include Nimbalyst, OpenKnowledge, Ritemark (made for people who don't write code) and markjason (a small Mac app for reading and editing agents' files). No product leads this group yet, and these apps are young, so expect them to change quickly.

Features that set Markdown editors apart

Within each group, a few features stand out when you work with an AI agent. Check these before you choose:

Plain files in your own folders - An agent can work only with files it can open. Choose an editor that saves each document as a .md file in a folder you choose, not inside the app's own library. Then you can switch editors later without converting anything.
Formatted editing or a preview - Some editors let you edit the formatted document directly. Others show the raw text with a formatted preview beside it, or switch between a reading view and an editing view.
Reloading when a file changes - An agent may rewrite a document while you have it open. A good editor shows the new version at once, keeps your place in the document, and never loses what you typed. Test this before you rely on an editor. Open a long document, ask your agent to change it, and watch to see the display change.
A folder view and search - A project holds many documents. A sidebar that lists the folder's files, and searches across all of them, helps you find the file the agent just wrote.
Links between documents - An agent's documents often link to other files in the project. Knowledge managers open those links and show which notes link back. This feature is not important when you work in an AI project.
Seeing what changed - Code editors and Git show exactly which lines an agent changed. Unlike code editors, most Markdown editors don't. Some of the editors made for AI agents show the changes themselves.
Export and sharing - Many editors export to PDF, Word or a web page, so you can share a nicely formatted document with people who don't use Markdown.
AI inside the editor - Some editors include their own AI chat or agent, usually connected to an AI account you pay for. If you already use Claude Code or Codex, the agent works on the same files, so the editor doesn't need AI of its own.
Price and license - Markdown editors range from free and open source, to a one-time purchase, to a subscription. Many good ones are free.

Working with your computer and an agent

With a Markdown editor, the files in a project folder become a place where you and an AI agent work together. The agent writes plans and notes, and you read them, correct them, and decide what it does next. Open your Markdown editor when you start a project with an agent, and keep it open beside the agent while you work.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.