<p align="center"> <img src="assets/img/icon.png" width="150" alt="logo" /> </p>

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 files (.rmd, without evaluating r code), MDX files (.mdx, without JSX rendering), Cursor Rulers (.mdc), Quarto files (.qmd), Api Blueprint files (.apib) 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
    • Mermaid diagrams
    • 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 /Applications/QLMarkdown.app # Default path; change if necessary

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:

touch /tmp/qlmarkdown.md && mdls -name kMDItemContentType /tmp/qlmarkdown.md && rm /tmp/qlmarkdown.md

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

This application handle these UTIs:

• public.markdown
• com.rstudio.rmarkdown
• com.unknown.md
• io.typora.markdown
• net.daringfireball.markdown
• net.ia.markdown
• org.apiblueprint.file
• 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)
• dyn.ah62d4rv4ge80c6dmqk (dynamic UTI for unassociated .apib 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 :smile:.
• 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. | |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.| |<a name="heads-anchors"></a>Heads anchors|Create anchors for the heads to use as cross internal reference. Each anchor is named with the lowercased caption, stripped of any