Binary Markdown Editor

An open-source visual Markdown editor for VS Code, independently maintained by BinaryOutlook. Edit Markdown in a rendered view, switch to source when needed, copy multiline code accurately, and keep the outline the way you prefer.

Binary Markdown builds on Any Markdown by raggbal and contributors, licensed under MIT. The visual editor and most existing features come from that project. BinaryOutlook maintains this project's changes, releases, and support. See Acknowledgments and the changelog for provenance.

Development now continues in this standalone repository. The original fork retains earlier reviews and releases, with v0.2.1 as its final product release. Original Git history, upstream attribution, and applicable license notices are preserved. See the repository transition guide for historical links and contributor instructions.

Open source, releases and support

Binary Markdown is proudly open source. Official releases are published periodically, when a set of changes has completed release validation; we do not promise a fixed release schedule.

You are welcome to build, study, and modify the extension between releases. For development builds, we recommend starting from main, where changes are integrated. Other branches may contain incomplete experiments. An unreleased build has not necessarily undergone the same validation as an official release.

Bug reports from development builds are welcome—even when the affected commit is not the latest release or the current tip of main. Please include the full commit ID, whether you made local changes, your environment, and clear reproduction steps. This helps us check out the same revision and investigate.

We will make a reasonable effort to reproduce and diagnose reported problems. We may ask you to test a newer commit, and fixes will normally land in current development rather than being backported to every historical revision.

Access to the source is central to this project. Building your own version is an intended way to use Binary Markdown.

Start with the documentation index for editor guides, export, building and validation. The reports index separates dated findings from current instructions; release notes describe individual versions.

Install

Download a version from GitHub Releases, which identifies published builds. The current source version is 0.2.1, with Windows validation and editor/export improvements described in the version notes. Check the chosen release's notes for supported environments and limitations. Marketplace and Open VSX publication remain future work.

Download the .vsix and its SHA-256 checksum from the chosen release, or build from source.
In VS Code, open Extensions, select … → Install from VSIX…, and choose the file.
Open a Markdown document and select Reopen Editor With… → Binary Markdown.

The extension is optional: installing it does not change your default Markdown editor. You can choose Configure Default Editor… yourself if you prefer to use it for every Markdown document.

The extension ID is BinaryOutlook.binary-markdown. It has separate commands, settings, and editor registration from Any Markdown. Read the migration guide if you used an earlier test build.

The package declares VS Code 1.85.0 or later. Validation targets local desktop VS Code on Windows x86-64, macOS ARM64 and Ubuntu x86-64; see the version notes for scope and validation evidence. The Windows validation guide describes the added checks; historical release records apply only to the platforms they list. Other editors and platforms need their own compatibility checks.

Features

Inherited from Any Markdown:

Visual editing and a source-mode toggle for .md and .markdown files.
Headings and outline navigation; bold, italic, strikethrough, lists, task lists, and blockquotes.
Tables, links, images, code blocks with syntax highlighting, and YAML front matter.
Mermaid diagrams and KaTeX expressions in fenced mermaid and math blocks.
An action palette, keyboard shortcuts, multiple themes, and seven interface languages.
Synchronization with external file changes, including changes made by coding tools.

Changes developed for Binary Markdown:

Inline and display equations with dollar or backslash delimiters, source-preserving editing, and complete multiline TeX rendering in existing math fences. See the equation guide.
Code-block copying preserves rendered line breaks, indentation, and meaningful blank lines.
Outline visibility can be remembered per file or globally, with a configurable initial state.
Opening the outline does not mark the Markdown document as edited.
Independent Binary Markdown names and identifiers throughout the extension and desktop sources.
Experimental HTML, PDF, DOCX and EPUB export, with local conversion and visible progress.
Protected YAML front matter and a generated TOC refreshed on save or with its refresh button; see the front matter and TOC guide.
A source-stamped VSIX and Copy Build Information command for reproducible bug reports.

The code-copy and outline-state improvements were also proposed upstream as [PR #8](https://github.com/raggbal/any-markdown/pull/8) and [PR #9](https://github.com/raggbal/any-markdown/pull/9). Binary Markdown's release decisions are independent of those PRs.

Configure the editor

Open Settings (Cmd+, on macOS or Ctrl+, on Windows/Linux) and search for Binary Markdown. Settings can be applied at User or Workspace scope.

Setting	Default	Purpose
`binary-markdown.outlineDefaultOpen`	`true`	Start with the outline open when no remembered state exists.
`binary-markdown.outlineStateScope`	`file`	Remember each file separately, or choose `global` to share visibility across files and workspaces.
`binary-markdown.outlineActiveColor`	`theme`	Choose the outline highlight color: theme, blue, green, orange, red, or purple.
`binary-markdown.toolbarMode`	`simple`	Use the compact toolbar or choose `full`.
`binary-markdown.tableToolbarPosition`	`auto`	Place table controls in available space, with a top-bar fallback. Explicitly choose any corner, either vertical side, or `top-bar`. The controls also offer a three-choice position menu.
`binary-markdown.theme`	`things`	Choose `github`, `sepia`, `night`, `dark`, `minimal`, `perplexity`, or `things`.
`binary-markdown.fontSize`	`16`	Editor font size in pixels.
`binary-markdown.language`	`default`	Editor interface language: follow VS Code, or select a supported language.
`binary-markdown.imageDefaultDir`	`""`	Image save directory; empty means the document's directory.
`binary-markdown.forceRelativeImagePath`	`false`	Prefer relative Markdown image paths when an absolute image directory is configured.
`binary-markdown.enableDebugLogging`	`false`	Enable diagnostic logging when investigating an issue.

Settings descriptions and option explanations follow VS Code's display language. English, Japanese, Simplified Chinese, Traditional Chinese, Korean, Spanish, and French are supported; other display languages fall back to English. Use Configure Display Language in the Command Palette and restart VS Code to change the display language. The binary-markdown.language setting controls the editor interface independently of these settings descriptions.

To start new files with a closed outline:

{
  "binary-markdown.outlineDefaultOpen": false,
  "binary-markdown.outlineStateScope": "file"
}

A remembered visibility overrides the initial default. Changing the default does not erase previously saved outline states. These settings control the editor's outline, not VS Code's Explorer sidebar.

Everyday commands

Search for Binary Markdown in the Command Palette. Commands include opening the editor, switching source mode, opening as text, comparing as text, inserting tables or a table of contents, and undo/redo.

Action	macOS	Windows/Linux
Open action palette	`Cmd+/`	`Ctrl+/`
Toggle source mode	`Cmd+.`	`Ctrl+.`
Open as text	`Cmd+Shift+.`	`Ctrl+Shift+.`

The editor guide covers formatting, keyboard operations, and images. Export commands and Copy Build Information are also available here.

Experimental export

Export supports HTML, PDF, Word (.docx), and EPUB in local desktop VS Code on macOS, Linux and Windows. HTML/PDF follow supported editor rendering; DOCX/EPUB prioritize editable content and structure. See the version notes and the export validation history for tested systems and limitations.

Remote-SSH export is not yet supported. The menu explains this restriction and marks every format unavailable. To export now, open a local copy of the Markdown file and its referenced assets in desktop VS Code on macOS, Linux or Windows. Installing Pandoc or a browser does not enable export in a remote window.

Save the named Markdown file, then select the sharing-arrow button immediately to the right of the VS Code-logo toolbar button. Choose a format from its dropdown. Unsaved work produces a save-and-retry message; export does not save automatically. The job shows its actual stage, supports cancellation, and reports the saved path and any fallback warnings.

Format	Tool to install	Initial output goal
HTML	None beyond the running extension	Standalone supported rendering with embedded resources
PDF	Chrome, Chromium, or Microsoft Edge	Prepared HTML printed by a headless browser with simple pagination; white page by default
Word / EPUB	Pandoc	Editable text and document structure; layout can differ from browser output

Install Pandoc using its official instructions; Homebrew users can use brew install pandoc. For PDF, install Google Chrome or another supported Chromium-family browser. Native tools are user-managed and are not downloaded or bundled by the extension. A browser is the PDF rendering engine; HTML and Pandoc formats do not require it.

Open VS Code Settings and search for binary-markdown.export. Leave the following machine-specific settings empty for automatic detection, or supply an absolute executable path:

Setting	Example macOS executable path	Example Linux executable path	Example Windows executable path
`binary-markdown.export.pandocPath`	`/opt/homebrew/bin/pandoc`	`/usr/bin/pandoc` or an absolute user-space installation path	`C:\Program Files\Pandoc\pandoc.exe`
`binary-markdown.export.browserPath`	`/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`	`/usr/bin/google-chrome`	`C:\Program Files\Google\Chrome\Application\chrome.exe`

An invalid manual path is reported instead of silently selecting a different tool. Reopen the export menu after installing a tool to rescan. The initial workflow requires a trusted workspace; remote hosts, browser VS Code and Electron-app export are deferred.

Files are saved beside the Markdown source with the same filename stem. An occupied name uses the final eight SHA-256 hexadecimal characters of the completed output, then _2, _3, and so on if needed. An identical hash-named file is reused, and existing files are preserved. No destination dialog is shown.

PDF defaults to a white page with GitHub light appearance. Disable binary-markdown.export.pdfWhiteBackground in VS Code settings to fill the entire page, including margins, with the current editor theme. Text keeps its 16 mm inset. This setting does not change the editor, source images or other export formats.

Supported resources retain source resolution; missing or unsupported content receives a visible fallback and warning summary. PDF uses simple block fitting, so blank regions are acceptable. Advanced pagination, templates, compression, custom destinations and unsaved export remain future work. See export help for the initial format limitations and the subsystem outline for the agreed implementation scope.

Build and contribute

Start development builds from main, select the Node version in .node-version, then run:

git clone https://github.com/BinaryOutlook/binary-markdown.git
cd binary-markdown
npm ci
npm run package

The package command compiles the extension and writes dist/<name>-<version>.vsix, a SHA-256 checksum, and build information. It links installed documentation to the source commit. See building for historical revisions, isolated installation and verification, and CONTRIBUTING.md for tests and focused PRs.

Bug reports, translations, accessibility work and compatibility testing are welcome in the Binary Markdown issue tracker. Reports from identifiable older development commits are welcome too.

Project history and license

The reference archive preserves superseded README, website, screenshots, and upstream release notes for historical reference. Archived instructions describe the original project and should not be used to install Binary Markdown.

For the 0.2.0 transition, Binary Markdown is licensed under GNU AGPL version 3 or later (AGPL-3.0-or-later). Earlier MIT releases retain their original terms. The retained MIT notice covers inherited upstream code and prior MIT contributions; third-party components retain their own licences. See NOTICE and the licensing guide for scope, retained grants and matching source. Project and dependency licence notices are included in packaged builds. The Electron desktop sources are retained under the Binary Markdown name; desktop installers and their compatibility are a separate release effort.