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
gemcommand, use:sudo gem install asciidoctor
-
Download a zipped binary of this plug-in. Unzip and move
AsciiDoc.qlgeneratorinto/Library/QuickLook. Note the plug-in will not work if installed to a user directory~/Library/QuickLookdue to restraints imposed by the sand-boxing of Quick Look plug-ins. -
Lastly, open Terminal and run the command
qlmanage -rto 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.