clydeclements / AsciiDocQuickLook

A QuickLook plugin to preview AsciiDoc files.

AsciiDoc Quick Look

Introduction

This is a Quick Look plug-in for AsciiDoc format files. It renders a preview of an AsciiDoc file selected in the Finder by using Asciidoctor.

Installation

• By default this plug-in uses Asciidoctor to render the preview. Therefore, first install that program via your preferred method. For example, to install via the system gem command, use:

  sudo gem install asciidoctor

• Download a zipped binary of this plug-in. Unzip and move AsciiDoc.qlgenerator into /Library/QuickLook. Note the plug-in will not work if installed to a user directory ~/Library/QuickLook due to restraints imposed by the sand-boxing of Quick Look plug-ins.

• Lastly, open Terminal and run the command qlmanage -r to reset the Quick Look Server.

Customization

The preview of an AsciiDoc file is generated by converting it to HTML via Asciidoctor and displaying the resultant HTML. This process can be customized by setting a preference to override the converter:

defaults write ca.bluemist2.AsciiDocQuickLook AsciiDocConverter /path/to/my_converter

The last part of the above command must give the full path to an executable that accepts one argument, the name of the AsciiDoc file to be previewed, and writes the corresponding HTML format on standard output. For example, create a shell script called asciidoc_to_html with content similar to the following:

#!/bin/bash
export PATH=/usr/local/bin:$PATH
asciidoctor -b html5 -a nofooter -a icons=font -o - "$1"

Ensure the script is executable (use chmod +x asciidoc_to_html) and place it in your ~/bin folder (create the folder if it does not exist). Lastly, set the converter preference:

defaults write ca.bluemist2.AsciiDocQuickLook AsciiDocConverter ~/bin/asciidoc_to_html

To Do

• A process should support sudden termination for the best user experience; see Terminating Processes. This plug-in works by launching an Asciidoctor process. Could the handling of this process be improved?

• Consider using asciidoctor.js to generate previews. Examine QLSwift to see how it generates previews using JavaScript. This method would not require the Asciidoctor program to be installed (though it would require distribution of asciidoctor.js) and it would not need to launch a separate process.

Release History

• 1.0 (2017-11-06): Initial release

License

Copyright © 2017 Clyde Clements

The AsciiDoc Quick Look plug-in is distributed under the MIT license. See the license file for more information.