I sit down to write an article. I open my Markdown editor. I type one sentence in Persian.
And the period is at the wrong end.
Not a crash. Not an error message. Just something small that is wrong, and stays wrong. I have been looking at it for years.
The moment it breaks
Type a Persian sentence in almost any Markdown editor. Then look at what you get.
The period you typed at the end shows up at the beginning. Your bullet points sit on the left edge, but your text runs to the right. Numbers in an ordered list flip. Parentheses point the wrong way — ( closes and ) opens.
Now write one English word in the middle of the line. The whole paragraph moves around it. You did not change what the sentence says. You only changed the direction, and the editor treated that as permission to rearrange everything.
So you go looking for the setting. You always find the same one: a single dropdown, at the top, for the whole file.
That is what never worked for me. A real page is not one direction. Mine looks like this:
- a Persian paragraph
- a code block, which must run left-to-right
- another Persian paragraph
- a heading with an English product name inside it
Pick either value in that dropdown and half the file is wrong.
One setting cannot describe a real page.
And this is not a small group of people. Persian, Arabic, Hebrew, Urdu. That is a lot of writers. Most of them either fight a preview pane, or give up and type raw text into a plain box.
I already tried to fix this once
Here is something I should say early: this is my second attempt.
A while ago I wrote a VS Code extension called RTL Markdown. You rename a file to .rtl.md, run a command, and your Markdown finally renders right-to-left.
27,000 people installed it.
That number changed how I saw this problem. I wrote a small, awkward extension for something I thought was only mine. Then 27,000 people went looking for the same thing and found it. The problem was never mine. It just belonged to nobody.
But the extension was a hack. I should say how bad a hack it was.
To work at all, it edits VS Code's own core files. You install it and restart. Then VS Code tells you your installation is damaged. And my own documentation has to tell you to ignore that warning.
It got worse. Every VS Code update can remove the patch. Every Persian file needs a different file extension. And it never handled a mixed page. Renaming the file flips the whole document at once. That is the same "one setting for the file" idea. It is what broke everything in the first place.
It sits at version 0.0.11. I stopped working on it.
You cannot fix an editor from the outside. It does not want to be changed.
What you can use today
I am not the only one who tried. Dôwn is an online Arabic Markdown editor built for the same problem, and it does its job well.
Here is the honest map of the options, including my own failed one:
| Raw Markdown, any editor | VS Code + my old extension | An online RTL editor | Macfolio | |
|---|---|---|---|---|
| Direction is decided | not at all | per file (.rtl.md) |
per app | per paragraph |
| Persian and English on one page | ❌ | ❌ | ⚠️ | ✅ |
| See it formatted as you type | ❌ | preview only | ✅ | ✅ |
| Files stay on your disk | ✅ | ✅ | in a browser | ✅ |
| Works with no internet | ✅ | ✅ | ❌ | ✅ |
| Survives an editor update | ✅ | ⚠️ the patch is removed | ✅ | ✅ |
Every column solves something. None of them solved all of it — on my machine, offline, in a window I can keep open all day.
So I built my own
The second time, I stopped trying to change somebody else's editor. I wrote my own.
I named it Macfolio — Mac + Folio, a leaf of a book.
🔥 Macfolio is free and open source → github.com/dalirnet/macfolio
A table being edited in place — not a preview of one. On the left, projects and their documents. At the bottom, the AI helper and what the last turn cost.
I knew what I wanted, because I had missed it for years:
- Native. A real SwiftUI app for macOS and iPad. No Electron, no browser tab, no account.
- Correct. Direction that follows the text, not a dropdown.
- Mine. Documents as plain files, in a folder I own.
Direction is decided per paragraph
Here is the whole fix. I want to be honest about how small it is. Every paragraph in the editor carries one attribute:
<p dir="auto">لوبیا قرمز را از شب قبل بخیسان.</p>
<p dir="auto">Then drain it in the morning.</p>
dir="auto" means: find the first letter in this paragraph that has a direction, and follow it. A Persian letter first, so the paragraph goes right-to-left. A Latin letter first, so it goes left-to-right.
Per paragraph. Every time. There is no language setting anywhere in the app, because there is nothing left to ask you.
The same app, the same window, no setting changed between this and the picture above. The list numbers moved to the right side on their own. The sidebar keeps English and Persian names side by side.
The Persian flows right. The code block stays left. Neither one disturbs the other. The app also ships with its own fonts: Sofia Sans for Latin letters, Dana for Persian. English never looks out of place inside a Persian line.
There is one more detail that took me a while to notice. Dana's letters are taller than Sofia's. If the line height follows the font, a Persian line becomes taller than an English line. Then the page jumps every time you switch language mid-document. So the line height is fixed to fit both faces. Your paragraphs stay the same height, whichever direction they run.
dir="auto"has been in browsers for years. The rule was never the hard part — my extension proved you can even add it to VS Code. The hard part is applying it per paragraph, and you can only do that if you own the editor.
You can see it while you type
There is a second half to this problem. The tools that do get direction right are usually read-only previews. You type raw text on one side and watch the result on the other. So you never really look at your document while you write it.
Macfolio edits in place. Headings, bold and italic, lists, quotes, code blocks, tables, links, and images all appear as you type them. Markdown shortcuts still work. Type #, -, >, or three backticks, and it becomes the real thing immediately. Your hands never leave the keyboard.
One honest note: I did not write the editor. Lexical does the hard part. It runs inside a WebKit view in the app. macOS already has WebKit, so nothing extra ships with it. My work was the direction handling, the Mac app around it, and everything below this line.
Your documents are just files
There is no database and no cloud. A project is a folder. A document is a .md file.
~/Documents/Macfolio/
└── Field Notes on Rain/
├── 01 First Light.md
├── 02 The Estuary.md
├── 03 A Table of Tides.md
└── images/
└── estuary.png
Plain text. You can grep it, back it up, put it in git, or open it in any other editor tomorrow.
Each document also keeps a small block of information at the top, called front matter. It sits between two --- lines at the very start of the file. The editor hides it, and you edit it in a simple form instead of typing it by hand:
title: A Table of Tides
order: 3
date: 2026-08-20
tags: [tides, notes]
draft: false
This is the same shape a Jekyll site or a dev.to post already expects. That is the point. These are documents you will publish somewhere. They are not locked inside an app.
I care about this more than I used to. My VS Code extension died because it depended on the inside of a program I did not control. Files do not have that problem.
Your writing should outlive the app you wrote it in.
The AI is a helper, not a ghostwriter
I did not want something that writes for me. I wanted the boring half of editing to stop taking so long.
So the AI does the work you would otherwise do by hand:
- make this paragraph shorter
- fix this wording
- make the list consistent
- this sentence repeats itself, rewrite it
- translate this line
It opens the file, makes the change, and the editor updates while you watch. There is nothing to copy out of a chat window and paste back in.
It also knows where you are. Your open document, your selection, and the current line go with your message:
| You say | It already knows |
|---|---|
| "fix this paragraph" | which paragraph your caret is in |
| "rewrite the selection" | the exact text you highlighted |
| "remove this line" | the line — not its best guess |
The footer shows the work as a live checklist. It also prints the token usage for each turn under the reply, so a small fix never costs a surprising amount.
Bring your own backend
There is no sign-in screen. In Settings you pick one of three:
- Claude Code — the CLI you already have installed. No new login, and nothing appears in the web panel. macOS only.
- Claude API — your own key. Opus 4.8, Sonnet 5, or Haiku 4.5.
- OpenAI — your own key. GPT-4o or GPT-4.1, and the mini versions.
The two API backends cannot open files by themselves. So Macfolio does that part for them. It gives the model read, write, and edit tools, and lets it work on your files until the change is done. On iPad there is no CLI, so a key is all you need.
When the AI gets it wrong
An AI helper is fast. That also means it can be fast in the wrong direction.
So every project gets its own git repo. One click saves a snapshot. The history view lets you look through the timeline and restore an earlier one. Nothing after it is destroyed.
That is what makes "just try it and see" a safe thing to say to a machine that edits your text. (macOS.)
Made to stay simple
I already watched one of my own tools break from the inside. So I kept this one plain:
- Native Swift. Not a browser wrapped in an app.
- No account, no tracking. Nothing to sign into. Nothing sends your text anywhere.
- Your settings and your writing are files. Delete the app and your work is still there.
- It follows your Mac. System accent color, light or dark.
The rest is small:
-
⌘Fsearches every document and jumps to the match. - Images in a project are listed next to its documents.
- Right-click a document to edit its front matter, rename it, or delete it.
- One click resets the AI session when you want to start fresh.
Try it
Download Macfolio-1.0.2.zip from the latest release. Unzip it, then move Macfolio.app into your Applications folder. The whole app is about 4 MB.
The first time you open it, right-click the app and choose Open. A normal double-click will be blocked, because the app is not notarized yet. If macOS still refuses, allow it under System Settings → Privacy & Security.
Or build it yourself. The Mac app builds with swiftc, and you do not need an Xcode project:
git clone https://github.com/dalirnet/macfolio.git
cd macfolio
make run # build and launch
make release # universal release build
make run also builds the editor with Vite and puts it inside the app. It installs the npm packages the first time. If you do not have npm, the app still runs — you just get a read-only preview instead of the editor. The iPad app builds from Macfolio.xcodeproj in Xcode.
You need macOS 13 or later, or iPadOS 16 or later. You also need one AI backend: the Claude Code CLI, or a Claude or OpenAI key. A ⭐ on GitHub helps other people find it:
👉 https://github.com/dalirnet/macfolio
If you write Markdown in Persian, Arabic, Hebrew, or Urdu, you already know this problem. You have worked around it for so long that you stopped noticing you were doing it. You pick a direction at the top of the file. You accept that half the page will look wrong.
You do not have to. The fix is one attribute, in the right place. It only took me two attempts and one abandoned extension to put it there.
I built it for myself, in the language I actually write in. Maybe it is what you have been waiting for too.
Top comments (0)