Beta Install & Update Guide

This guide covers how to download, install, and update the MD Editor desktop app during the initial beta. Because the beta builds are not yet notarized on macOS and are unsigned on Windows, your OS will show security warnings on first launch. The steps below walk you through bypassing them safely.

Downloading the Latest Build

1. Go to the GitHub Releases page (opens in a new tab).
2. Find the latest release (look for the tag marked Latest).
3. Under Assets, download the file for your platform:

macOS: Bypassing Gatekeeper

Because the beta .dmg is not notarized, macOS Gatekeeper will block it on first open.

Installation steps

1. Open the downloaded .dmg file and drag MD Editor into your Applications folder.
2. Double-click MD Editor in Applications. macOS will show a dialog:

   "MD Editor" cannot be opened because the developer cannot be verified.

3. Click OK to dismiss the dialog (do not move to Trash).
4. Open System Settings → Privacy & Security (or System Preferences → Security & Privacy on older macOS).
5. Scroll down to the Security section. You should see:

   "MD Editor" was blocked from use because it is not from an identified developer.

6. Click Open Anyway.
7. In the confirmation dialog, click Open.
8. MD Editor will launch and you will not see the warning again on this machine.

Alternative: right-click to open

You can also right-click (or Control-click) the app icon in Applications, choose Open, and then click Open in the security prompt. This skips the System Settings step.

Windows: Bypassing SmartScreen

Unsigned Windows executables trigger Microsoft Defender SmartScreen.

Installation steps

1. Run the downloaded mdedit-*-setup.exe.
2. Windows SmartScreen will show a blue dialog:

   Windows protected your PC

3. Click More info (below the warning message).
4. Click Run anyway.
5. The installer will proceed normally. Follow the on-screen prompts to complete the installation.

Note: SmartScreen only appears on the first run of a new unsigned build. After installation, launching MD Editor from the Start menu or desktop shortcut will not trigger the warning.

Linux: AppImage Setup

MD Editor ships as an AppImage (opens in a new tab) on Linux — a self-contained, portable executable that does not require installation.

Prerequisites

Some distributions do not include FUSE 2 (required to mount AppImages). Install it if needed:

# Ubuntu / Debian
sudo apt install libfuse2
 
# Fedora
sudo dnf install fuse
 
# Arch Linux
sudo pacman -S fuse2

Running the AppImage

# 1. Make the file executable
chmod +x mdedit-*.AppImage
 
# 2. Launch it
./mdedit-*.AppImage

Optional: integrate with your desktop

To add MD Editor to your application launcher, you can use appimaged or manually create a .desktop entry. Most distributions also support right-clicking the AppImage in a file manager and choosing Properties → Permissions → Allow executing as program.

Updating the App

In-app updates (when available)

MD Editor will notify you when a new version is available. Click Restart & Update in the notification to download and apply the update automatically. This requires an active internet connection.

Manual updates

If in-app updates are not yet enabled for your build:

1. Download the latest release from the GitHub Releases page (opens in a new tab).
2. macOS: Open the new .dmg and drag MD Editor into Applications, replacing the previous version.
3. Windows: Run the new installer; it will upgrade the existing installation in-place.
4. Linux: Replace the old .AppImage file with the new one and re-run the permission step (chmod +x).

Troubleshooting

Authentication / OAuth redirects not working

The desktop app uses a custom URL protocol (mdeditai://) to handle OAuth callbacks from providers such as GitHub.

• macOS / Linux: The protocol should be registered automatically on first launch. If login does not complete, try quitting and relaunching MD Editor, then attempt sign-in again.
• Windows: Ensure the installer finished successfully — it registers the protocol handler during installation. Re-running the installer will re-register it if needed.

App does not start after update

1. Quit MD Editor completely (check the system tray on Windows/Linux).
2. Relaunch the app. If it still fails, clear the app cache:
   • macOS: ~/Library/Application Support/mdedit/
   • Windows: %APPDATA%\mdedit\
   • Linux: ~/.config/mdedit/
3. Delete the Cache folder inside that directory, then relaunch.

Finding log files

Application logs can help diagnose startup or runtime issues:

You can open the log folder quickly via the app menu: Help → Show Logs.

Reporting a bug

If you encounter an issue not covered here, please open a GitHub issue (opens in a new tab) and attach the relevant log file.