QLMarkdown

QLMarkdown is a macOS Quick Look extension to preview Markdown files.

This application is not intended to be used as a standalone markdown file editor or viewer.

Please note that this software is provided "as is", without any warranty of any kind.

If you like this application and find it useful, buy me a coffee!

The Quick Look extension can also preview rmarkdown (.rmd) files (without evaluating r code), Quarto files (.qmd) and textbundle packages.

You can download the last compiled release (as universal binary) from this link.

• Screenshots
  • Quick Look Markdown preview
• Installation
• Markdown processing
• Difference with the GitHub Markdown engine
• Settings
  • Themes
  • Options
  • Extensions
    • Emoji
    • Inline local images
    • Mathematical expressions
    • Syntax Highlighting
    • YAML header
• Command line interface
• Build from source
  • Dependency
• Note about security
• Note about the developer

Screenshots

Quick Look Markdown preview

Installation

You can download the last compiled release (as universal binary) from this link or you can install the Application with Homebrew:

brew install --cask qlmarkdown

The precompiled app is not notarized or signed, so the first time you run the app the system may show a warning about the impossibility to check for malicious software.

To fix, you can launch the app with right click (or ctrl click) on the app icon and choose the open action.

You can also execute this command from the terminal:

$ xattr -r -d com.apple.quarantine "FULL PATH OF THE QLMarkdown.app (you can drag the file to get the pull path)"

Alternatively, after trying to launch the app for the first time, you can open the System Preferences > Security & Privacy > General (tab) and click the Open Anyway button.

This will resolve the error of an unsigned application when launching the app.

To use the Quick Look preview you must launch the application at least once. In this way the Quick Look extension will be discovered by the system. After the first execution, the Quick Look extension will be available (and enabled) among those present in the System preferences/Extensions.

If you have problems, try moving the application to the trash and then back in the Applications folder. If the QLMarkdown Preview Extension is present (and checked) in the list of Quick Look Extensions in the System preferences but the .md files are not displayed it is probably due to other applications that have registered support for that type of file. You can change the order of priority of the Quick Look Extensions inside the System preferences.

Finally, the problems may depend on how the .md files were registered on the system by other applications.

In the terminal try the following command:

mdls -name kMDItemContentType PATH_OF_AN_EXISTS_MD_FILE

The output is the UTI associated with the .md file.

This application handle these UTIs:

• public.markdown
• com.rstudio.rmarkdown
• com.unknown.md
• net.daringfireball.markdown
• net.ia.markdown
• org.quarto.qmarkdown
• org.textbundle.package
• com.nutstore.down
• dyn.ah62d4rv4ge8043a (dynamic UTI for unassociated .md files)
• dyn.ah62d4rv4ge81e5pe (dynamic UTI for unassociated .rmd files)
• dyn.ah62d4rv4ge81c5pe (dynamic UTI for unassociated .qmd files)

Please inform me of any other UTI associated to .md files.

Markdown processing

For maximum compatibility with the Markdown format, the cmark-gfm library is used. The library is a GitHub fork of the standard cmark tool to process the Markdown files.

Compared to the cmark-gfm, these extensions have been added:

• Emoji: translate the emoji shortcodes like :smile: to 😄.
• Heads anchors: create anchors for the heads.
• Highlight: highlight the text contained between the markers ==.
• Inline local images: embed the image files inside the formatted output (required for the Quick Look preview).
• Subscript: subscript text between the markers ~.
• Superscript: superscript text between the markers ^.
• Math: format the mathematical expressions.
• Syntax highlighting: highlight the code inside fenced block.
• YAML header: render the yaml header at the begin of rmd or qmd files.

Difference with the GitHub Markdown engine

Although GitHub has customized the cmark-gfm library, it does not use it directly in the rendering process of Markdown files (see this repository). GitHub uses a number of libraries in Ruby for parsing and formatting source code that cannot easily be converted into a compiled library.

The main difference between this application and GitHub is the formatting of the source code. Syntax highlighting uses a different library, so the formatting, colors scheme, and language token recognition are potentially different.

This application, when set to use the accurate engine for the language detection (used only when the language is not specified) uses a library derived from the Linguistic framework adopted by GitHub.

Settings

Launching the application, you can configure the options, enable the desired extensions and set the theme for formatting the Quick Look preview of Markdown files.

To make the settings effective you need to save them (cmd-s or menu File > Save settings) or enable the autosave option.

The window interface has an inline editor to test the settings with a markdown file. You can open a custom markdown file and export the edited source code.

Please note that this application is not intended to be used as a standalone markdown file editor or viewer but only to set Quick Look preview formatting preferences. No warning about unsaved markdown code is displayed when closing the application.

Themes

You can choose a CSS theme to render the Markdown file. The application is provided with a predefined theme derived from the GitHub style valid both for light and dark appearance.

You can also use a style to extend the standard theme or to override it. User customized style sheet must have the settings for both light and dark appearance using the CSS media query:

@media (prefers-color-scheme: dark) { 
    /* … */ 
}

The custom style is appended after the CSS used for the highlight the source code. In this way you can customize also the style of the syntax highlight.

Syntax highlighting extension allow to customize the appearance of the code blocks.

The theme popup menu has some extra commands available pressing the alt key.

Options

Option	Description
Smart quotes	Convert straight quotes to curly, --- to em dashes and -- to en dashes.
Footnotes	Parse the footnotes. Footnotes are not supported by GitHub.
Hard break	Render softbreak elements as hard line breaks.
No soft break	Render softbreak elements as spaces.
Inline HTML (unsafe)	Render raw HTML and unsafe links (javascript:, vbscript:, file: and data:, except for image/png, image/gif, image/jpeg, or image/webp mime types) present in the Markdown file. By default, HTML tags are stripped and unsafe links are replaced by empty strings. This option is required for preview SVG images.
Validate UTF	Validate UTF-8 in the input before parsing, replacing illegal sequences with the standard replacement character (U+FFFD �).
Show about info	Insert a footer with info about the QLMarkdown app.
Show debug info	Insert in the output some debug information.
Render as source code	Show the plain text file (raw version) instead of the formatted output. Syntax highlighting remains.

Extensions

Extension	Description
Autolink	Automatically translate URL to link and parse email addresses.
Emoji	Enable the Emoji extension.
GitHub mentions	Translate mentions to link to the GitHub account.
Heads anchors	Create anchors for the heads to use as cross internal reference. Each anchor is named with the lowercased caption, stripped of any punctuation marks (except the dash) and spaces replaced with dash (-). UTF8 character encoding is supported.
Highlight	Highlight the text contained between the markers ==.
Inline local images	Enable the Inline local images extension.
Math	Enable the formatting of math expressions.
Strikethrough	Strikethrough text inside tildes. You can choose to detect single or double tilde delimiters.
Sub/Superscript	Allow to subscript text inside ~ tag pairs, and superscript text inside ^ tag pairs. Please note that the Strikethrough extension must be disabled or set to recognize double ~.
Syntax highlighting	Enable the Syntax highlighting extension.
Table	Parse table as defined by the GitHub extension to the standard Markdown language.
Tag filter	Strip potentially dangerous HTML tags (<title>, <textarea>, <style>, <xmp>, <iframe>, <noembed>, <noframes>, <script>, <plaintext>). It only takes effect if the option to include HTML code is enabled.
Task list	Parse task list as defined by the GitHub extension to the standard Markdown language.
YAML header	Enable the YAML header extension.

Tou can also choose if open external link inside the Quick Look preview window or in the default browser.

The Quick Look window option allow you to force a custom size for the content area of the Quick Look window. Use with caution on macOS before version 12 Monterey.

Emoji

You can enable the Emoji extension to handle the shortcodes defined by GitHub. You can render the emoji with an emoticon glyph or using the image provided by GitHub (internet connection required).

Multibyte emoji are supported, so :it: equivalent to the code \u1f1ee\u1f1f9 must be rendered as the Italian flag 🇮🇹.

Some emoji do not have an equivalent glyph on the standard font and will be replaced always with the relative image.

A list of GitHub emoji shortcodes is available here.

Inline local images

You can enable the Inline image extension required to preview images within the Quick Look window by injecting the images into the HTML code. The Quick Look extension, for security limitations, cannot access to the local images defined inside the Markdown code, so embedding the data it's a way around the limitation.

For security reasons are handled only URLs without schema (e.g., ./image.jpg, image.jpg or assets/image.jpg), or with the file schema (e.g., file:///Users/username/Documents/image.jpg) referring to existing files with an image mime type. With the file:// schema you must always set the full path. For images inside the same folder of the Markdown file do not use the file:// schema and also the path ./ is optional.

The extension process both images defined in the Markdown syntax and also with HTML <img> tag if the raw HTML code option is enabled.

Mathematical expressions

This extension allow to format the mathematical expressions using the LaTeX syntax like GitHub. Math rendering capability uses MathJax display engine.

Inline math expressions are delimited with a dollar symbol $. Block expressions are delimited with a double dollar symbols $$.

Alternatively, you can use the ```math code block syntax to display a math expression as a block.

The MathJax library is loaded from cdn.jsdelivr.net. The library is loaded if the markdown code contains ```math code blocks or one or more dollar sign.

Syntax Highlighting

This extension highlights the source code inside a fenced box.

The rendering engine is based on the Highlight library embedded in the app.

You can customize the settings:

• Colors scheme (for light and dark appearance).
• Line numbers visibility.
• Word wrap options.
• Tabs replacements.
• Font.
• Guess engine for undefined languages.

Some colors scheme (especially those for light appearance) uses a white background that is the same of the Markdown document, making the code block not immediately recognizable. For this reason, it is possible to override the background color in order to use a personal one or the one defined by the Markdown theme.

When the code block does not specify the language, it is possible to activate a guessing function. Two engines are available:

• Simple guess: it is based on the magic library;
• Accurate guess: it is based on the Enry library, that is a Golang porting of the Ruby linguist library used by GitHub.

If no language is defined and the guessing fail (or is not enabled), the code is rendered as normal text.

YAML header

You can enable the extension to handle a yaml header at the beginning of a file. You can choose to enable the extensions to all .md files or only for .rmd and .qmd files.

The header is recognized only if the file start with ---. The yaml block must be closed with --- or with ....

When the table extension is enabled, the header is rendered as a table, otherwise as a block of code. Nested tables are supported.

Command line interface

A qlmarkdown_cli command line interface (CLI) is available to perform batch conversion of markdown files.

The tool is located inside the QLMarkdown.app/Contents/Resources folder (and should not be moved outside).

You can create a symbolic link into your $PATH to use the tool from any folder. Open Terminal.app and type:

ln -s /Applications/QLMarkdown.app/Contents/Resources/qlmarkdown_cli /usr/local/bin/qlmarkdown_cli

Usage: qlmarkdown_cli [-o <file|dir>] <file> [..]

Arguments:
 -h    Show this help and exit.
 -o    <file|dir> Destination output. If you pass a directory, a new file is 
       created with the name of the processed source with html extension. 
       The destination file is always overwritten. 
       If this argument is not provided, the output will be printed to the 
       stdout.
 -v    Verbose mode. Valid only with the -o option.

Options:
 --footnotes on|off
 --hard-break on|off
 --no-soft-break on|off
 --raw-html on|off
 --smart-quotes on|off
 --validate-utf8 on|off
 --code on|off
 --debug on|off

Extensions:
 --autolink on|off
 --emoji image|font|off
 --github-mentions on|off
 --heads-anchor on|off
 --highlight on|off
 --inline-images on|off
 --math on|off
 --table on|off
 --tag-filter on|off
 --tasklist on|off
 --strikethrough single|double|off
 --syntax-highlight on|off
 --yaml rmd|qmd|all|off

Unspecified rendering options will use the settings defined in the main application.

To handle multiple files at time you need to pass the -o arguments with a destination folder.

The CLI interface uses the same settings as the Quick Look extension, but you can override it if you wish.

Any relative paths inside raw HTML fragments are not updated according to the destination folder.

Build from source

When you clone this repository, remember to fetch also the submodule with git submodule update --init.

Some libraries (Sparkle, Yams and SwiftSoup) are handled by the Swift Package Manager. In case of problems it might be useful to reset the cache with the command from the menu File/Packages/Reset Package Caches.

Dependency

The app uses the following libraries built directly from Xcode:

• highlight for syntax highlighting.
• magic, used to guess the source code language when the guess mode is set to simple.
• Enry, used to guess the source code language when the guess mode is set to accurate.
• PCRE2 and JPCRE2 used by the heads extension.

libpcre require the autoconf utility to be build. You can install it with homebrew:

brew install autoconf

Because Enry is developed in go, to build the wrapper library you must have the go compiler installed (you can use brew install go).

The compilation of cmark-gfm require cmake (brew install cmake).

Note about security

To allow the Quick Look view of local images the application and the extension has an entitlement exception to allow only read access to the entire system.

On Big Sur there is a bug in the Quick Look engine and WebKit that cause the immediate crash of any WebView inside a Quick Look preview. To temporary fix this problem this Quick Look extension uses a com.apple.security.temporary-exception.mach-lookup.global-name entitlement.

Note about the developer

I am not primarily an application developer. There may be possible bugs in the code, be patient. Also, I am not a native English speaker 😅.

Thanks to setanarut for the app icon and the CSS style.

This application was developed for pleasure ❤️.

If you find this application useful, buy me a coffee!