To edit a .md file without breaking it, change the words and leave the symbols around them alone: the # before a heading, the pipes in a table, the spaces before a sub-bullet, the three backticks around code. Edit in a plain text or Markdown editor rather than Word or Notes, and keep a way to undo before you save.
Why does editing a .md file break it?
Editing a .md file breaks it because in a .md file the symbols are the formatting. Move one and the meaning changes.
A # at the start of a line makes a heading. A row of | makes a table. Two spaces at the start of a line tuck a bullet under the one above. There's no hidden layer keeping things in place, so a stray keystroke goes straight into the structure. If the symbols are new to you, what a .md file is explains each one.
Three things cause most of the damage:
- A small slip. You delete a pipe, a space or a backtick along with the word you meant to change.
- An app that "helps". Some apps swap straight quotes for curly ones, or two hyphens for one long dash. That's lovely in a letter and wrong in a .md file.
- An editor that rewrites the whole file. Some tools save by rebuilding the file from scratch in their own preferred style. The page looks the same, but spacing, list markers and table layout change in lines you never touched.
What usually breaks in a .md file, and how do I fix it?
The parts of a .md file that usually break are headings, bold, links, frontmatter, code blocks, sub-bullets and tables. This table shows each one broken and fixed: find the part that looks wrong on the page, then compare your text with the fixed version.
| What broke | What you see on the page | Broken | Fixed |
|---|---|---|---|
| Heading | A plain line starting with # | #Timeline | # Timeline |
| Bold | Stars on the page instead of bold | ** Potato ** | **Potato** |
| Bold, half closed | The wrong words turn bold, or stars show | **Owner: Maya | **Owner:** Maya |
| Link | Square and round brackets on the page | [spec] (https://example.com) | [spec](https://example.com) |
| Frontmatter (the details block at the top) | The block shows as text, or an app reports an error | title: Plan: phase 2 | title: "Plan: phase 2" |
| Curly quotes in frontmatter or code | Same as above, even though it has quotes | title: “Plan: phase 2” | title: "Plan: phase 2" |
| Code block | Everything after it looks like code | The closing line of three backticks was deleted | Put three backticks back on their own line |
| Sub-bullet | It lands at the wrong level, or joins the line above | Indented by a different amount than its neighbors | Indent it to line up with the words of the bullet above |
| Table | Lines of text full of pipes | The dashes row has fewer cells than the header | See the example below |
| Table, split | The table stops halfway | An empty line between two rows | Delete the empty line |
Why these rules? A few come straight from the Markdown specs most apps follow:
- A heading's
#must be followed by a space (CommonMark spec). - Opening
**can't be followed by a space, which is why** Potato **shows its stars (CommonMark spec). - A link's square brackets must be followed immediately by the round ones (CommonMark spec).
- If a code block's closing backticks are missing, the code block runs to the end of the file (GitHub Flavored Markdown spec).
- Frontmatter is written in YAML, and a value can't contain a colon followed by a space unless you put it in straight quotes (YAML spec).
The table that stopped being a table
Tables break most often, and the cause is usually one row near the top. The header row and the row of dashes under it must have the same number of cells, or the table isn't recognized at all (GitHub Flavored Markdown spec).
| Step | Owner | Due | |---|---| | Beta | Maya | Oct 1 | | Launch | Sam | Oct 15 |
| Step | Owner | Due | |---|---| | Beta | Maya | Oct 1 | | Launch | Sam | Oct 15 |
| Step | Owner | Due | |---|---|---| | Beta | Maya | Oct 1 | | Launch | Sam | Oct 15 |
| Step | Owner | Due |
|---|---|---|
| Beta | Maya | Oct 1 |
| Launch | Sam | Oct 15 |
The body rows are more forgiving. A row with a missing cell still shows, with a blank cell at the end. A row with an extra cell drops the extra one. A table also ends at the first empty line, which is why a stray blank line cuts it in half (same spec).
Need a real pipe inside a cell, like "Q3 or Q4" written with a bar? Type a backslash before it, \|, so it isn't read as a new column. More on tables in how to make Markdown tables readable.
How do I edit a .md file in TextEdit safely?
You can edit a .md file safely in TextEdit, as long as it stays in plain text and stops "fixing" your punctuation.
- Open the .md file in TextEdit. It opens as plain text, which is what you want. You'll see every symbol.
- Turn off the helpers for this document. Choose
Edit › Substitutionsand untick Smart Quotes and Smart Dashes if they're ticked (Apple Support). Smart quotes turn"into curly quotes, and smart dashes turn two hyphens into one long dash. - Change only the words. Click inside the word, not at the start of the line, so you don't catch the symbols.
- Save with ⌘S.
To stop this happening in every new document, choose TextEdit › Settings, click New Document, and turn off Smart quotes, Smart dashes and Text replacement, or tick Smart quotes and dashes in rich text documents only (Apple Support).
Two more TextEdit traps:
- Starting a new file. New TextEdit documents may start as rich text, with a ruler and font buttons. Choose
Format › Make Plain Textfirst. When you save, check the name ends in.md. TextEdit has a setting that adds ".txt" to plain text files (Apple Support), and a file calledplan.md.txtwon't open as Markdown. - No preview. You won't see whether the table survived until you open the file in a Markdown reader.
If something goes wrong, File › Revert To › Browse All Versions shows earlier saved versions in TextEdit and many other Mac apps (Apple Support).
Avoid editing a copy in Word, Pages or Notes and pasting it back. Those apps work in rich text, so symbols can be lost or changed on the way.
Can I edit a .md file safely in VS Code or Typora?
Yes, VS Code and Typora are both good for editing a .md file safely. Each has one thing to watch.
VS Code (free). Open the file, then press ⌘K V to show the formatted preview beside the text. The VS Code docs say the preview shows "changes reflected in real-time as you edit" (VS Code docs), so a broken table shows up the moment you break it. Its Local History, in the Timeline view, keeps up to 50 saved versions of each file by default (VS Code docs).
The thing to watch is formatting on save. It's off by default (VS Code docs), but if you've turned it on with a formatter such as Prettier, the whole file gets rewritten when you save. Prettier describes this plainly: it "reprints it from scratch" in its own style (Prettier docs). Fine for code. Surprising in a plan your AI will read next.
Typora ($14.99 once, checked 28 September 2026). You edit the formatted page directly, so you rarely touch a symbol. To check what's underneath before you save, press ⌘/ for Source Code Mode (Typora support).
Editors with a preview you can type into. Some tools save a formatted-view edit by rebuilding the Markdown. Cursor users, for example, have reported tables being reformatted after editing in its Preview mode (Cursor forum). If a tool does this, edit in its plain text view instead.
How do I edit a .md file safely in One Clear Reader?
In One Clear Reader you edit a .md file's Markdown text for free, check exactly what changed before it's saved, and undo if it went wrong.
- Open the file and press ⌘E. On the free version this opens the Markdown text for editing. (With Pro, ⌘E opens the visual editor and ⇧⌘E opens the text.)
- Change the words.
- Press ⌘S. Before anything is written, Check the changes shows the lines you added and removed. If you caught a pipe or a backtick by mistake, you'll see it here. Choose Save to file, or Keep editing to go back.
- Look at the page. It updates when you save. The text editor doesn't show a live preview as you type, so this is your moment to check the table.
If it still went wrong, you have two ways back:
- Version history (press ⌘K and search for it, or use the History button). A copy is kept before each save and each time the file changes from outside. Compare any copy with the current file, then Restore. The free version shows the newest 3 copies. Pro shows up to 25.
- Restore Version Before Last Save, a menu command that undoes your last save during the current session.
One Clear Reader also guards against the classic accident with AI files: two writers at once. If Claude rewrites the file while you're typing, One Clear Reader holds the outside change and blocks your save with "A newer version exists", so neither version silently wins. A locked or read-only file is never overwritten. Press Esc to cancel an edit, and it asks before throwing your changes away.
Editing the formatted page (Pro)
If you'd rather not see symbols at all, Edit like a document (Pro) lets you edit the formatted page, like a word processor. Tables are edited cell by cell, with Tab to move between cells, and you can add or remove rows and columns.
Blocks you didn't touch are written back to the file exactly as they were, byte for byte. So fixing a date in one paragraph doesn't reformat the table below it or tidy the frontmatter at the top. The rest of the file stays the way your AI wrote it.
Should I just ask Claude or ChatGPT to edit the .md file?
Often, yes. For anything bigger than a word or two, asking Claude or ChatGPT to edit the .md file is quicker, and the AI won't miss a pipe. The risk is that it "improves" things you didn't ask about. So ask narrowly, then check.
Here's a prompt you can copy:
In plan.md, change the launch date in the Timeline table from Oct 15 to Oct 22.
Change nothing else. Keep every other line exactly as it is,
including spacing, symbols and the table layout.
Then list the lines you changed.Then check what it actually did. If the file is open in One Clear Reader when the AI saves it, the page reloads and tells you how many sections are new or changed since the last refresh, with a button to jump to each one. Version history also keeps a copy from before the outside change, so you can compare the two. How to see what your AI changed covers this in more detail.
For several fixes at once, select the words on the page, press ⌥⌘N to add a note to each, then use Copy as prompt. It copies one prompt with the file path, each quoted passage and your note, ready to paste back into Claude. The free version allows 3 notes per document.
Why keep a .md file clean when you edit it?
A .md file is worth keeping clean because your AI will read it again. Every symbol you leave alone is one the next tool can rely on.
One Clear Reader lets you read and edit Markdown for free, with Check the changes before every save and a version history behind you. The visual editor is part of Pro ($19.99 a year, or $59 once), and a new install gets a 30-day trial of everything with no card. The editing help page has every shortcut.
Questions people ask
Can I edit a .md file in TextEdit?
Yes. TextEdit opens .md files as plain text and saves them back as .md. Turn off Smart Quotes and Smart Dashes under Edit › Substitutions first, so it doesn't change your punctuation.
Why did my Markdown table stop working after I edited it?
A Markdown table usually stops working because the header row and the dashes row no longer have the same number of cells, or an empty line crept in between rows. Count the pipes in the first two rows and remove any blank lines inside the table.
Why do stars show instead of bold text in my .md file?
Stars usually show instead of bold because there's a space just inside them, like ** word **, or one pair is missing. Write **word** with no spaces between the stars and the word.
Will editing in a visual editor change the rest of my .md file?
It depends on the editor: some visual editors rebuild the whole .md file when they save. One Clear Reader's visual editor (Pro) writes back every block you didn't touch exactly as it was.
How do I undo a bad edit to a .md file?
Use the app's version history. On a Mac, many apps offer File › Revert To › Browse All Versions. VS Code keeps Local History in its Timeline view, and One Clear Reader keeps a copy before each save.
Is it safer to let Claude or ChatGPT make the edit?
For bigger changes, often yes. Ask it to change only the lines you name and to list what it changed, then check the result before you rely on it.