coleslaw/docs/plugin-api.md

General Use

1. A lisp file should be created in coleslaw's plugins directory.

2. Any necessary lisp libraries not loaded by coleslaw should be included like so:

   (eval-when (:compile-toplevel :load-toplevel) (ql:quickload '(foo bar)))

3. A package should be created for the plugin code like so:

   (defpackage :coleslaw-$NAME (:use :cl) (:export #:enable) ...)

   where $NAME is the pathname-name of the lisp file. (eg. :coleslaw-disqus for disqus.lisp)

4. An enable function should be present even if it's a no-op. Any work to enable the plugin is done there.

Extension Points

• New functionality via JS, for example the Disqus and Mathjax plugins. In this case, the plugin's enable function should call add-injection with an injection and a keyword. The injection is a function that takes a Document and returns a string to insert in the page or nil. The keyword specifies whether the injected text goes in the HEAD or BODY element. The Disqus plugin is a good example of this.

• New markup formats, for example the ReStructuredText plugin, can be created by definining an appropriate render-text method. The method takes text and format arguments and is EQL-specialized on the format. Format should be a keyword matching the file extension (or pathname-type) of the markup format. (eg. :rst for ReStructuredText)

• New hosting options, for example the Amazon S3 plugin, can be created by definining a deploy :after method. The method takes a staging directory, likely uninteresting in the :after stage. But by importing *config* from the coleslaw package and getting its deploy location with (deploy-dir *config*) a number of interesting options become possible.

• New content types, for example the static page content type, can be created by definining a subclass of CONTENT along with a template, and render, page-url, and publish methods. The PAGE content type cheats a bit by reusing the existing POST template.

• New service integrations, for example crossposting to twitter/facebook/tumblr/livejournal/etc, is also possible by adding an :after hook to the deploy method. The hook can iterate over the results of the get-updated-files to crosspost any new content. The Twitter plugin is a good example of this.