Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/clydeclements/AsciiDocQuickLook

A QuickLook plugin to preview AsciiDoc files.
https://github.com/clydeclements/AsciiDocQuickLook

asciidoc asciidoctor macos quicklook quicklook-plugin

Last synced: 28 days ago
JSON representation

A QuickLook plugin to preview AsciiDoc files.

Awesome Lists containing this project

README 

        
= 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.