marka.md

the marka manual

local markdown for the work you actually want to share.

Marka is a desktop markdown editor for plain files, live preview, and clean AI context bundles. It stays local, keeps the interface quiet, and leaves your notes as regular files on disk.

local-first MIT macOS · Windows · Linux

getting started

The app is file-first: open one or more folders, edit normal files, and keep ownership of the project structure on disk.

On macOS, you can install from the DMG or use Homebrew: brew install --cask mattenarle10/tap/marka-md. Homebrew users can update with brew update && brew upgrade --cask marka-md; the signed in-app updater remains available too.

windows · WinGet

Install marka.md from the WinGet community repository:

winget install --id mattenarle10.markamd --exact --source winget

To check for and install a newer version available through WinGet:

winget upgrade --id mattenarle10.markamd --exact --source winget

The WinGet package may trail the latest GitHub release. You can also use the Windows installer from the download menu for the latest release. View the package manifests ↗

  1. 01
    Open a folder. Pick the notes or project folder you want to work from. Pin favorites and let the sidebar become your local context library.
  2. 02
    Open or create a file. Markdown opens beside a live preview. Use tabs to keep several notes close; CSV opens as a lightweight read-only table preview.
  3. 03
    Stage context. Use the sidebar buttons to stage files. The context tray shows file and token counts, then copies one bundle when you are ready.

open from your terminal

macOS. Open a Markdown file from Ghostty, Codex, or any terminal without hunting through Finder.

  1. Install the latest marka.md release and open the app.
  2. Open Help or the command palette and choose install marka command.
  3. Run marka --help in your terminal.
marka open notes.md
marka open --wait "review this.md"

Use marka open -- -draft.md for a name beginning with a dash.

The command accepts one existing .md, .markdown, or .mdx file. Relative paths work from your terminal's current folder.

--wait resumes when you close the file's tab or quit the app. Saving alone does not finish the wait. Cancelling an unsaved-close prompt keeps it waiting. Ctrl-C cancels the wait without closing your document.

for agents

Exit code 0 means the open request succeeded or the wait ended. It does not mean a person approved the document. Exit code 1 reports a launch/open failure, 2 reports invalid input, and 130 means the wait was cancelled.

command not found?

The app installs ~/.local/bin/marka. If that directory is missing from PATH, run this line and add it to your shell profile (usually ~/.zshrc) for future terminals:

export PATH="$HOME/.local/bin:$PATH"

The installer does not edit shell settings or overwrite unrelated commands. After moving the app, use the install action again to refresh the launcher.

why does Finder still show marka.md.app?

The new macOS bundle is marka.app. In-app updates preserve the older folder name. Quit normally, rename marka.md.app to marka.app in Applications, and reopen it. Reinstall the command afterward. Keep any existing destination and leave the signed bundle's contents alone.

writing + preview

editor + preview

The default split view keeps source and rendered markdown side by side. Code highlighting, Mermaid diagrams, media previews, task lists, and tables render beside the source. When you want more room, open the preview in its own window and keep editing in the main app.

modes + find

Reading mode clears the chrome for proofreading; editor-only mode stays focused on text. Search, opt-in Vim mode, and platform shortcuts are there when you need them.

themes

Theme groups keep the picker tidy: mono, Catppuccin, crafted palettes, AI-inspired Claude, Codex, Gemini, and Cursor styles sit alongside quiet mono and crafted palettes. The interface also supports Traditional Chinese.

quick inserts

The command palette can insert 2×2 or 3×3 tables, bulleted and numbered lists, and fenced code blocks without breaking your flow.

context bundles

The context tray is the main Marka workflow. Stage related markdown files from the sidebar, then copy a single bundle with relative paths and estimated token counts. It is built for passing project notes, specs, changelogs, and drafts to another tool without copy-pasting fragments one by one. 

path/to/file.md

---

file contents...

workspace + files

supported inputs

Markdown is editable. CSV is previewed as a table. Plain text fallback is available when a file is safe to read.

Use the command palette while editing to insert common markdown blocks without stopping to hand-type table scaffolds: tables, bulleted lists, numbered lists, and fenced code blocks are built in.

  • Markdown: edit .md, .markdown, and .mdx files.
  • CSV: open .csv files as a fast table preview.
  • Plain text: unsupported text files can be opened as text when the app can read them safely.
  • Local images: relative image paths in markdown resolve from the current file folder.
  • Workspace care: drag files to move them, undo file operations, and let Marka notice external file changes.
  • Native files: right-click files to copy paths, reveal in file manager, rename, delete, or open with the default app.

export

PDF export prints the rendered preview with clean document margins and browser headers disabled by the app. Mermaid diagrams and code blocks render before the print handoff; code blocks can also be copied directly from preview.

shortcuts

These use the macOS symbols. On Windows and Linux, use the matching Ctrl-based shortcut.

⌘K open command palette
⌘⇧O open folder
⌘O open file
⌘N new buffer
⌘T new tab
⌘1…9 switch to tab
⌘S save
⌘⇧S save as
⌘B show or hide sidebar
⌘. reading mode
⌘⇧. editor-only mode
⌘⇧C copy current markdown
⌘F find in the current file
⌘P open or close the separate preview
⌘/ help

troubleshooting

why did a file open in another app?

Binary files, oversized files, and unsupported formats are blocked from the editor. If a file looks like safe text, Marka can offer “open as text”.

where are settings stored?

UI preferences are local to the desktop app. Your files remain regular files on disk. No account, cloud sync, or telemetry is involved.

where do I report issues?

Use GitHub issues for bugs, feedback, and feature requests.