QLMarkdown

[](https://github.com/sbarex/QLMarkdown/releases)

# QLMarkdown QLMarkdown is a Mac OS application that provides: - a Quick Look extension for viewing Markdown files - an experimental Shortcut extension for converting Markdown files to HTML - a command-line executable for converting Markdown files to HTML - a graphical interface for configuring Quick Look preview display settings. > **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__](https://www.buymeacoffee.com/sbarex)! 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. Also `.mermaid` files are rendered wrapped inside a mermaid fenced block (the mermaid extension must be enabled). You can download the last compiled release from [this link](https://github.com/sbarex/QLMarkdown/releases). - [Screenshots](#screenshots) - [Quick Look preview](#quick-look-preview) - [Shortcut Command preview](#shortcut-command-preview) - [Installation](#installation) - [Uninstall](#uninstall) - [Markdown processing](#markdown-processing) - [Differences with GitHub's Markdown engine](#differences-with-githubs-markdown-engine) - [Quick Look Settings](#quick-look-settings) - [Themes](#themes) - [Options](#options) - [Extensions](#extensions) - [Emoji](#emoji) - [Inline local images](#inline-local-images) - [Mathematical expressions](#mathematical-expressions) - [Mermaid diagrams](#mermaid-diagrams) - [Note about external Javascript libraries (MathJax and Mermaid)](#note-about-external-javascript-libraries-mathjax-and-mermaid) - [Syntax Highlighting](#syntax-highlighting) - [YAML header](#yaml-header) - [Command line interface](#command-line-interface) - [Shortcut Commands](#shortcut-commands) - [Build from source](#build-from-source) - [Dependency](#dependency) - [FAQ](#faq) - [Note about security](#note-about-security) - [Note about the developer](#note-about-the-developer) ## Screenshots ### Quick Look preview ### Shortcut Command preview ## Installation You can download the last compiled release from [this link](https://github.com/sbarex/QLMarkdown/releases) or you can install with [Homebrew](https://brew.sh/): ```shell brew install --cask qlmarkdown ``` _The precompiled app is notarized and signed_. **You must launch the application at least once**. In this way the Quick Look extension will be discovered by the system and some shared files are installed for the Shortcut extension. After the first execution, the Quick Look extension will be available (and enabled) among those present in the System preferences/Extensions. You can check using the button "Open System Settings > … > Quick Look panel…" on the main App. The application store some support files on `~/Library/Group Containers/group.org.sbarex.qlmarkdown`. **Please note that the contents of the `highlight` and `js` subfolders may be overwritten by the App.** ## Uninstall To uninstall the application, simply drag it to the trash. Support files can be deleted by removing the folder `~/Library/Group Containers/group.org.sbarex.qlmarkdown`. ## Markdown processing For maximum compatibility with the Markdown format, the [`cmark-gfm`](https://github.com/github/cmark-gfm) library is used. The library is a GitHub fork of the standard cmark tool to [process the Markdown files](https://github.github.com/gfm/). Compared to the `cmark-gfm`, these extensions have been added: - `Definition list`. - `GitHub alert`: GitHub-style alerts. - [`Emoji`](#emoji): translate the emoji shortcodes like `:smile:` to :smile:. - [`Heads anchors`](#heads-anchors): create anchors for the heads. - `Highlight`: highlight the text contained between the markers `==`. - [`Inline local images`](#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`](#mathematical-expressions): format the mathematical expressions with the MathJax library. - [`Mermaid`](#mermaid-diagrams): render the diagrams with the Mermaid library. - [`Syntax highlighting`](#syntax-highlighting): highlight the code inside fenced block. - `Wikilinks`. - [`YAML header`](#yaml-header): render the yaml header at the begin of `rmd` or `qmd` files. ## Differences with GitHub's Markdown engine Although GitHub has customized the [`cmark-gfm`](https://github.com/github/cmark-gfm) library, it does not use it directly in the rendering process of Markdown files (see [this repository](https://github.com/github/markup)). 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. ## Quick Look 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. ### 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: ```css @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. If your style use a content column with a different width, declare it to size the Quick Look window accordingly: ```css :root { --content-max-width: 1200px; } ``` Only `px` values are recognized. The theme popup menu has some extra commands available pressing the `alt` key. It is possibile to set a custom base font size. This size (in points) will be used for set the dimension of `1rem` in the css style sheet. ### Options |Option|Description| |:--|:--| |Smart quotes|Convert straight quotes to curly, ```---``` to _em dashes_ and ```--``` to _en dashes_.| |Footnotes|Parse the footnotes. **Superscript extension must be disabled.**| |Hard break|Render `softbreak` elements as hard line breaks.| |No soft break|Render `softbreak` elements as spaces. Has no visual effect on HTML formatting.| |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](#emoji).| |Definition list|Render definition lists (a term line followed by `: description` lines).| |GitHub alert|GitHub-style alerts (`[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`) rendered as colored callouts.| |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 the underscore) and each space replaced with a dash (`-`). UTF8 character encoding is supported.| |Highlight|Highlight the text contained between the markers `==`.| |Inline local images|Enable the [Inline local images extension](#inline-local-images).| |Math|Enable the [formatting of math expressions](#mathematical-expressions).| |Mermaid|Enable the [Mermaid diagram](#mermaid-diagrams) extension.| |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 `~`**. Also the **Footnotes options must be disabled**.| |Syntax highlighting|Enable the [Syntax highlighting extension](#syntax-highlighting). | |Table|Parse table as defined by the GitHub extension to the standard Markdown language.| |Tag filter|Strip potentially dangerous HTML tags (``, `<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.| |Wikilinks|Render `[[Page Name]]` and `[[Target\|Display]]` wikilinks as links.| |YAML header|Enable the [YAML header extension](#YAML-header).| 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 suggest a custom size for the content area of the Quick Look window. macOS does not always honor this setting. With `Auto` the size is derived from the [content column](#themes) of the theme in use (960 x 1000 points with the predefined theme, reduced to fit the screen). In `Render as code` mode the window is wider. > _Use with caution on macOS before version 12 Monterey_. #### Emoji You can enable the Emoji extension to handle the shortcodes defined by [GitHub](https://api.github.com/emojis). You can render the emoji with an emoticon glyph or using the image provided by GitHub (internet connection required). Multibyte emojis are supported, so `:it:` equivalent to the code `\u1f1ee\u1f1f9` must be rendered as the Italian flag :it:. Some emojis do not have a glyph equivalent in the standard font and will always be replaced with the corresponding image. A list of GitHub emoji shortcodes is available [here](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#people--body). ### 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 this 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/D