AsciiDocQuickLook

AsciiDocQuickLook copied to clipboard

= AsciiDoc Quick Look

:url-releases: https://github.com/clydeclements/AsciiDocQuickLook/releases :url-what-is-asciidoc: http://asciidoctor.org/docs/what-is-asciidoc/ :url-asciidoctor: http://asciidoctor.org/ :url-terminating-processes: https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/Lifecycle.html#//apple_ref/doc/uid/10000172i-SW3-114794-BAJIBGGI :url-asciidoctorjs: http://asciidoctor.org/docs/install-and-use-asciidoctorjs :url-qlswift: https://github.com/lexrus/QLSwift

== Introduction

This is a Quick Look plug-in for {url-what-is-asciidoc}[AsciiDoc] format files. It renders a preview of an AsciiDoc file selected in the Finder by using {url-asciidoctor}[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 {url-releases}[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 {url-terminating-processes}[Terminating Processes]. This plug-in works by launching an Asciidoctor process. Could the handling of this process be improved?

• Consider using {url-asciidoctorjs}[asciidoctor.js] to generate previews. Examine {url-qlswift}[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 (C) 2017 Clyde Clements

The AsciiDoc Quick Look plug-in is distributed under the MIT license. See the link:LICENSE.txt[license] file for more information.