FluxMarkdown puts a full Markdown renderer in the Finder QuickLook

It runs where the Finder previews files

FluxMarkdown is a Markdown Preview Enhanced for macOS QuickLook, and the interaction it replaces is the space bar in Finder. The preview is where you would read a document you have not opened, and the value of the tool is that it renders the things a plain text preview cannot: diagrams, mathematical expressions, tables and charts. Installing is a cask:

brew install --cask xykong/tap/flux-markdown

The feature list is a rendering list rather than a feature list. There is Mermaid for architecture diagrams, flowcharts and sequence diagrams, KaTeX for inline and block mathematical expressions, GFM support for tables, task lists, strikethrough and GitHub Alerts, and syntax highlighting for more than forty languages. There are charts through Vega, Vega-Lite and Graphviz with DOT, an interactive table of contents panel that tracks the section you are reading, and YAML frontmatter parsed into a clean table.

The export path is what makes it more than a preview

Two features take the tool past the QuickLook use case. Export to PDF with Cmd+Shift+P and to HTML with Cmd+Shift+E, and the fact that it mentions a request from a V2EX user for exactly that. The second is position memory, where the app remembers the scroll position and the last viewed file, which sounds trivial until you have closed a long document and reopened it. There is also zoom and pan with Cmd plus, minus and zero, Cmd with scroll and pinch gestures, and themes in light, dark and a system-synchronised mode that follows the macOS appearance setting. The combination of export, remembered position and a themes panel is what separates this from the plain text preview that QuickLook would otherwise give you.

A long list of file extensions, because the Markdown ecosystem never converged

The file formats row is a list of fourteen extensions and that is itself a design statement:.md,.mdx,.rmd,.qmd,.mdoc,.mdc,.mmd,.livemd,.mkd,.mkdn,.mkdown,.mdwn,.mdown and.markdown. Those come from different tools:.qmd is Quarto,.rmd is R Markdown,.mdx is a JSX-flavoured Markdown, and.livemd is from a different editor family. A QuickLook generator that only recognised.md would have been much less useful in practice, and the list shows the author ran into the same fragmentation everyone does. The settings window adds toggles for Mermaid, KaTeX and Emoji rendering, a base font size control and a choice of code highlighting themes including GitHub, Monokai and Atom One Dark.

A web renderer inside a native app

The repository layout explains the architecture, and it is the most interesting part of the project. There is a `Sources/` directory for the Swift application, a `Tests/` directory, a `web-renderer/` directory, and a `Package.swift` alongside a `project.yml`, which is an XcodeGen specification rather than a checked-in Xcode project. The Makefile shows how the pieces fit together. The `build_renderer` target installs the web renderer's npm dependencies and runs its build, `generate` depends on the renderer being built and then runs xcodegen, refusing with a clear message if xcodegen is not installed, and it reads the version from a `.version` file to produce the marketing version and the build number. The `app` target then runs xcodebuild against the generated project for the Markdown scheme on an arm64 macOS destination. So the rendering engine is web technology and the shell around it is native Swift, which is a common and sensible split for a document renderer that has to handle HTML, CSS and a JavaScript diagram library.

Releases are automated, and the version is generated

The release history explains the numbering. The recent tags are v1.36.556 from 2026-10-12, v1.35.547 from the same day and v1.35.539 from the day before, so the third component is a build counter rather than a semantic version, and the patch level moves constantly. The repository contains an `appcast.xml` and a `.sparkle-keys/` directory, which suggests an appcast-based update feed. The Makefile has a `release` target and a `delete-release` target, and the release process is therefore part of the build tooling rather than a manual step. The last push to the master branch was on 2026-10-12, and there is a `macports/` directory alongside `scripts/`, `benchmark/`, `docs/` and an `openspec/` directory, which suggests the work is tracked as specifications.

The licence question is a two-way choice

FluxMarkdown is dual licensed and the README explains both halves. The open source option is GPL-3.0, which is free for personal, educational and open-source use, requires that any modifications are also open-sourced under GPL-3.0, with the full terms in the LICENSE file. The commercial option is required for closed-source or proprietary products, permits distribution without open-sourcing your modifications, is described in the LICENSE.COMMERCIAL file, and licensing inquiries go to a contact address. The stated reason for the dual licensing is that it keeps the project free and open for the community while allowing commercial use without the GPL obligations for those who need it. There is also a comparison table against three other QuickLook Markdown plugins, and it is unusually honest about its own method: the entries are based on public readmes and release notes at the cited links, and where a feature is not mentioned in the sources it is marked as not mentioned. That is a small thing, but it is the difference between a comparison and a set of claims.

Editorial conclusion

Adopt FluxMarkdown if you want to read Markdown with diagrams and math in Finder rather than in an editor, since that is exactly the gap the QuickLook generator fills. Do not adopt it expecting the other QuickLook Markdown generators to match it feature for feature, since the comparison table in the documentation is built from public readmes and marks unmentioned features as such. Verify first whether the dual licence suits you, because the GPL-3.0 option requires open sourcing your modifications and the commercial option does not, and check that the version you install supports the file extension you actually work in, since the list of supported extensions is long and specific.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. xykong/flux-markdown on GitHub