thymer docs
Documentation/Markdown Mirror

Markdown Mirror

Markdown Mirror keeps a folder on your computer in sync with your workspace. Every page is a plain Markdown file. Search it with grep, process it with scripts, open it in your editor or hand it to an AI agent. Changes sync both ways, usually within a few seconds, while everyone else keeps working in Thymer.

For an overview, see thymer.com/markdown-mirror.

Turn it on

Markdown Mirror runs in the desktop app:

  1. Open the workspace you want to mirror.
  2. Open Settings → Markdown Mirror. Or press ⌘PCtrl+P for the command palette and search for Markdown Mirror.
  3. Choose an Output Directory: an empty folder on your computer. A folder that Dropbox, iCloud or a similar service syncs is experimental: Thymer already syncs your devices, so a plain local folder is the safer choice.
  4. Switch on Enable Markdown Mirror and Enable two-way sync.

The first export writes the whole workspace. From then on the mirror runs while the desktop app is open with that workspace selected. Edit a file, and the change is in Thymer a moment later; edit in Thymer, and the file updates.

Without two-way sync the folder is an always-current export that you can read but whose edits don’t flow back. The CLI’s mdmirror command makes the same kind of one-way copy from the terminal; see The CLI.

How files map to pages

One folder per collection, one .md file per page: Projects/Launch plan.md is the page “Launch plan” in the Projects collection. Rename the file and the page is renamed, and the other way around; the same goes for a folder and its collection. Move a file into another folder and the page moves to that collection. Create a folder and you have a new collection; create a .md file and you have a new page. The layout is flat: a sub-page is an ordinary file in its collection’s folder, with a Sub-page of property.

Properties sit in a frontmatter block at the top of each file. See Files and frontmatter.

A collection’s folder can also show up inside one of your own project folders, for you and your agents to work on there. See Link a collection into a project folder.

Simultaneous edits

If a page changes in Thymer and on disk at the same time, both sets of changes are merged. Only when the exact same line changed on both sides does Thymer’s version win, and the disk version is kept in .thymer/conflicts.json.

Deleting

Delete a file and the page goes to Thymer’s Trash. Trash a page in Thymer and its file moves to the trashed/ folder. If a whole folder disappears at once, nothing is trashed until you check the folder and confirm, which protects you from a disconnected disk. Re-creating a deleted file does not restore the page; restore it from Trash instead.

Status and recovery

Settings → Markdown Mirror shows what the mirror is doing: running, stopped after an error, waiting for you to confirm a large deletion, taken over by another window, or paused because Thymer was reloaded in Safe Mode.

If it stopped, read the reason there first. A missing folder, a permissions problem, or a workspace that was rewound to an earlier state each need a look before you restart the mirror. After a rewind, compare the files with the workspace before turning two-way sync back on.

Don’t delete .thymer/ to get a mirror going again. It holds the state the mirror uses to tell your changes from Thymer’s, and without it the next sync starts from scratch.

Help: Markdown Mirror in the command palette has this summary inside the app.