Sarala: an open source WYSIWYG Markdown editor that renders diagrams, math and code inline

Most Markdown editors make you choose between two bad layouts. You either write raw syntax and imagine the result, or you split the window into source on the left and a preview on the right, then keep your eyes moving between them. For prose that is tolerable. For technical documents full of fenced code, tables, Mermaid flowcharts and LaTeX, the preview pane becomes the only place you can tell whether the document is right, and it is never where your cursor is.

Sarala is a free, open source desktop editor for macOS, Windows and Linux that removes the second pane. You type plain Markdown and each block renders in place. Click a paragraph and its Markdown appears so you can edit it. Click away and it renders again. Files on disk stay ordinary .md.

The idea will be familiar to anyone who has used Typora. The differences are the licence (GPL-3.0), native rendering of Mermaid and D2 diagrams, an AI assistant that proposes changes as diffs, and voice typing that runs entirely on your machine. The rest of this piece covers how those parts behave, how to install the current release (1.3.3) on each platform, and the rough edges to check before adopting it for a team.

Inline rendering instead of a preview pane

The editing model works block by block. A paragraph, heading, table or code fence shows as finished output until you put the cursor in it. Then it switches to its Markdown source, and it renders again once you move elsewhere. You read and edit on the same page. There is no scroll-sync between two panes to drift out of alignment, and no guessing which rendered line maps to which source line.

This matters more for technical writing than for notes. A long runbook with a dozen tables and code blocks is hard to proofread as raw source, because pipes, backticks and indentation hide the content. Rendering inline means the document already looks like the version your readers will see. You only meet the syntax when you are changing it.

The syntax itself is the Markdown you already write. Sarala does not add a proprietary format on top. That is the reason it can open existing repositories and vaults without converting anything, which is covered further down.

Mermaid and D2 diagrams in the page

Diagrams are where split-view editors are weakest. Most render Mermaid only in preview, if at all, and D2 support is rarer still. Sarala renders both inline: flowcharts, sequence diagrams and architecture maps sit in the document as diagrams and follow the active theme, so a dark theme gives you dark diagrams rather than a white box in the middle of the page.

To edit one, click the diagram and its source opens. A minimal Mermaid block looks like this:

```mermaid
flowchart LR
  user --> ingress --> service
```

Because the source stays a standard fenced block, the same file renders wherever else Mermaid is supported, for example on a code-hosting platform that renders Mermaid in Markdown. D2 is less widely supported by renderers, so if your documents get published somewhere outside Sarala, check that the target can render D2 blocks before you rely on them.

Math, code, tables and callouts

Equations render with KaTeX as you type, both inline and as display blocks, with optional equation numbering and references. A display equation is written the usual way:

$$ W = \frac{1}{\mu - \lambda} $$

Fenced code is syntax-highlighted for more than 100 languages, and the highlighting uses colours from your theme rather than a fixed palette. That keeps code readable when you switch between light and dark themes, which fixed-colour highlighters often get wrong.

The remaining block types cover what most engineering docs need:

• Tables are edited cell by cell instead of by realigning pipe characters. Alignment markers such as | :-- | --: | still live in the source.
• Task lists can be ticked with a click, which writes - [x] back to the file.
• GitHub-style callouts such as > [!WARNING] render as notes and warnings, so they match how the same files look on GitHub.

Choosing GitHub's callout syntax over an invented one is the useful detail here. A README or docs folder edited in Sarala keeps rendering correctly when it is pushed.

Working on files you already have

Sarala opens any folder of Markdown files: an Obsidian vault, a docs/ directory inside a Git repository, or notes exported from another editor. It edits the files in place and adds nothing to them. There is no hidden metadata directory to gitignore and no front matter injected into your documents.

For teams this is the property that decides whether a desktop editor is usable at all. Docs-as-code workflows depend on Markdown in the repository being the single source of truth, reviewed through pull requests. An editor that keeps state alongside the files, or rewrites them into its own dialect, creates noise in every diff. Sarala's stated approach is to leave the files as plain Markdown, which means one engineer can use it while the rest of the team keeps using their own editors.

One thing to check yourself: any WYSIWYG editor has to serialise its rendered model back to Markdown on save. Before adopting it across a repository, open a few existing files, make a one-character change, save, and run git diff to confirm that nothing else in the file was normalised.

An AI assistant that proposes diffs

Sarala includes an AI assistant you can ask to review, summarise or rewrite. Every change comes back as a diff that you accept or reject. It does not silently overwrite the document. For technical text this is the right default, because a model that 'tidies' a paragraph can just as easily change a flag name, a port number or a version string. Reviewing a diff makes that kind of edit visible before it lands.

The assistant does not ship its own model or account. It uses whichever agent you already have installed, so connection behaviour, sign-in and data handling are the agent's own. For anyone working under data-handling rules, that settles where document content goes when you invoke the assistant. Read the policy of the agent you connect, because Sarala itself does not decide it.

Offline voice typing and network behaviour

Voice typing works by holding a shortcut and talking. An open speech model on your computer turns the audio into text, and nothing is uploaded. The model is downloaded only when you turn voice typing on, so installations that never use the feature never fetch it.

The network footprint is short and stated plainly. Sarala goes online for three things only:

• checking for updates;
• loading images that your documents link to;
• downloading the speech model if you enable voice typing.

The AI assistant is outside that list because it runs through your external agent. For security reviews this is a manageable surface. Note the second item, though: a document that embeds remote images will make outbound requests when opened. That is normal Markdown behaviour, but it is worth knowing if you open untrusted files.

Installing on macOS, Windows and Linux

Release 1.3.3 is available for all three platforms. On macOS it supports Apple Silicon and Intel on macOS 10.15 or later (31.8 MB). The app is not notarized by Apple, so a .dmg install is blocked on first launch. After dragging it into Applications, clear the quarantine attribute once:

xattr -dr com.apple.quarantine /Applications/Sarala.app

Otherwise, open it, click Done when macOS blocks it, then use Open Anyway under System Settings › Privacy & Security. On macOS 14 or older, right-click and choose Open. A 'Sarala is damaged' message is the same Gatekeeper warning. The recommended route is Homebrew, which skips the prompt and lets brew upgrade handle updates:

brew tap solancer/sarala https://github.com/solancer/sarala
brew trust --cask solancer/sarala/sarala
brew install --cask --yes sarala

On Windows 10 and 11 (64-bit), run Sarala_1.3.3_x64-setup.exe (13.4 MB). It needs no administrator rights. The installer is not code-signed yet, so SmartScreen shows 'Windows protected your PC'. Click More info, then Run anyway, and verify the published checksums first if your policy requires it. For managed fleets there is a 15.0 MB .msi for deployment tools. Either way, updates install from inside the app.

Linux packages cover most distributions:

sudo snap install sarala
sudo apt install ./Sarala_1.3.3_amd64.deb
sudo dnf install ./Sarala-1.3.3-1.x86_64.rpm
chmod +x Sarala_1.3.3_amd64.AppImage && ./Sarala_1.3.3_amd64.AppImage

All releases, release notes and checksums are published alongside the source in the GitHub repository.

Where it does not fit, and what to watch for

Unsigned binaries. No Apple notarization and no Windows code signing means every first install starts with a security bypass. That is a small step for one developer. In an organisation that blocks unsigned executables, or trains people never to click Run anyway, it is a blocker. The .msi and Homebrew routes reduce the friction but do not change the signing status. Plan to verify checksums and get an exception before a team rollout.

Desktop only. There is no mobile app. Because the files are plain Markdown you can open them on other devices with any Markdown app, but Mermaid, D2 and KaTeX rendering will depend on what that app supports.

Portability of features. Mermaid fences, KaTeX math and GitHub callouts travel well. D2 blocks and equation numbering may not render in your publishing pipeline, so test the target before writing large documents around them.

Serialisation and licence. Confirm with git diff that saves do not reformat untouched content. Note too that GPL-3.0 has no bearing on using the editor or on the documents you write. It only matters if you plan to modify and redistribute Sarala itself. For engineers who write a lot of diagram-heavy, math-heavy Markdown and want the files to stay ordinary text in Git, those caveats are worth checking once, and the payoff is losing the preview pane for good.

This article draws on Open Source Alternatives to Reflector? and answers to it (1, 2), on the Stack Exchange network, licensed under CC BY-SA 4.0.